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Macro Assembler 



















ZERO PAGE MEMORY MAPS 


Keyboard Special Locations 

Location: 

Hex 

Decimal 

Description: 

$C000 

49152 -16384 

Keyboard Data 

$C010 

49168 -16368 

Clear Keyboard Strobe 


Video Display Memory Ranges 

Screen 

Page 

Begins at: 

Hex Decimal 

Ends at: 
Hex 

Decimal 

Text/Lo-Res 

Primary 

Secondary 

$400 

$800 

1024 

2048 

$7FF 

$BFF 

2047 

3071 

Hi-Res 

Primary 

Secondary 

$2000 

$4000 

8192 

16384 

$3FFF 

$5FFF 

16383 

24575 


Annunciator Special Locations 

Ann. 

State 

Address: 

Decimal 

Hex 

0 

off 

49240 

-16296 

$C058 


on 

49241 

-16295 

$C059 

1 

off 

49242 

-16294 

$C05A 


on 

49243 

-16293 

$C05B 

2 

off 

49244 

-16292 

$C05C 


on 

49245 

-16291 

$C05D 

3 

off 

49246 

-16290 

$C05E 


on 

49247 

-16289 

$C05F 


Input/Output Special Locations 

Function 

Address: 

Decimal 

Hex 

Read/Write 

Speaker 

49200 

-16336 

$C030 

R 

Cassette Out 

49184 

-16352 

$C020 

R 

Cassette In 

49256 

-16288 

$C060 

R 

Annunciators 

49240 

-16296 

$C058 

R/W 


through 

through 

through 



49247 

-16289 

$C05F 


Flag inputs 

49249 

-16287 

$C061 

R 


49250 

-16286 

$C062 

R 


49251 

-16285 

$C063 

R 

Analog Inputs 

49252 

-16284 

$C064 

R 


49253 

-16283 

$C065 



49254 

-16282 

$C066 



49255 

-16281 

$C067 


Analog Clear 

49264 

-16272 

$C070 

R/W 

Utility Strobe 

49216 

-16320 

$C040 

R 


Monitor Zero Page Usage 

Decimal 

0 1 

2 

3 

4 5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 


Hex 

$0 $1 

$2 

$3 

$4 $5 

$6 

$7 

$8 

$9 

$A 

$B 

$C 

$D 

$E 

$F 

0 

$00 















16 

$10 















32 

$20 














• 

48 , 

$30 














• 

64 

$40 













• 

• 

80 

$50 















96 

$60 















112 

$70 















128 

$80 















144 

$90 















160 

$A0 















176 

$B0 















192 

$C0 















208 

$D0 















224 

$E0 















240 

$F0 

















ORCA /M 


REFERENCE CARD 


Monitor Commands 


APPEND XXX 

ASML 

ASMLG 

ASSEMBLE 

BRUN XXX 

CATALOG XXX 

CMPL 

CMPLG 

CHECK 

COMPILE 

COMPRESS 

COPY 

DELETE XXX 

DOS 

EDIT 

EXPAND 

FREE 

LOAD XXX 

LINK 

LOCK XXX 

MARGIN X 

NEW 

NOEXPAND 

PEEK 

PRINT 

PROFF 

PRON 

QUIT 

RENAME XXX, yyy 
RESET 

RESTORE XXX 
RUN 

SAVE XXX 
SWITCH XXX, yyy 
TAB 
TIME 

UNLOCK XXX 
USER 

VOLUME X 


append file xxx 
assemble and link 
assemble, link and go 
assemble the file in memory 
execute file xxx 
catalog the disk 
compile and link 
compile, link and go 
check a disk 

compile the file in memory 
compress the disk 
copy files 

delete file xxx from disk 

boot DOS from slot x 

soft entry to text editor 

expand load 

display memory used 

load file xxx 

link edit 

lock file xxx 

set the left margin to x 

hard entry to text editor 

don’t expand load 

examine and change disk sectors 

print file 

turn printer off 

turn printer on 

exit the assembler 

rename file xxx 

reset modification count 

restore file xxx 

assemble, link and execute a program 
save file xxx 
switch files 
set tab line 

print the time and date 
unlock 'file xxx 

call the SUSER subroutine in the 

operating system 

set the volume number to x 


Copyright © 1983 

by Hayden Book Company Inc. 


Material on panels 9, 10, 11, and 12 from the 
Apple II Reference Manual, by permission of 
Apple Computer Inc. 



































































































/ e ^ 

<?<? <? 

’ / i? / ^ s ! 

A? \ ^ ^ ^ ^ ! 

ADC 


2 

4 

4* 

4* 

3 

4 

6 5* 1 

AND 


2 

4 

4* 

4* 

3 

4 

6 5* 1 

ASL 

2 


6 

7 


5 

6 

’ 

BCC 








3' . i 

BCS 








3' 

BEQ 








3' 

BGE 








3' 

BIT 



4 



3 



BMI 








3' 

BNE 








i 

BLT 








3' i 

BPL 








3' I 

BRK 

7 







1 

BVC 








3' ! 

BVS 








3' j 

CLC 

2 







j 

CLD 

2 








CLI 

2 







t 

CLV 

2 







f 

CMP 


2 

4 

4* 

4* 

3 

4 

6 6* j 

CPA 


2 

4 

4* 

4* 

3 

4 

6 5* 1 

CPX 


2 

4 



3 



CPY 


2 

4 



3 


* 

1 

DEC 



6 

7 


5 

6 

i 

DEX 

2 








DEY 

2 








EOR 


2 

4 

4* 

4* 

3 

4 

6 6* 

INC 



6 

7 


5 

6 


INX 

2 








I NY 

2 








JMP 



3 





6 

JSR 



6 






LDA 


2 

4 

4* 

4* 

3 

4 

6 5* 

LDX 


2 

4 


4* 

3 


■4 

LDY 


2 

4 

4* 


3 

4 


LSR 

2 


6 

7 


6 

6 


NOP 

2 








ORA 


2 

4 

4* 

4* 

3 

4 

6 5* 

PHA 

3 








PHP 

3 








PLA 

4 







! 

PLP 

4 








ROL 

2 


6 

7 


5 

6 

i 

ROR 

2 


6 

7 


6 

6 


RTI 

6 







( 

RTS 

6 







i 

SBC 


2 

4 

4* 

4* 

3 

4 

6 5* 

SEC 

2 







■ 

SED 

2 








SEI 

2 








STA 



4 

6 

6 

3 

4 

6 6 

STX 



4 



3 


4 

STY 



4 



3 

4 


TAX 

2 







i 

TAY 

2 








TSX 

2 








TXA 

2 








TXS 

2 







1 

TYA 

2 









If branch is not taken, 2 cycles. If branch crosses page boundary. 4 cycles 
Add 1 cycle if instruction crosses page boundary. 


The ASCII Character Set 

Decimal: 

128 

144 

160 

176 

192 

208 

224 

240 


Hex: 

$80 

$90 

$A0 

$B0 

$C0 

$D0 

$E0 

$F0 

0 

$0 

nul 

die 


0 

@ 

P 


P 

1 

$1 

soh 

del 

! 

1 

A 

Q 

a 

q 

2 

$2 

stx 

dc2 

" 

2 

B 

R 

b 

r 

3 

$3 

etx 

dc3 

# 

3 

C 

S 

c 

s 

4 

$4 

eot 

dc4 

$ 

4 

D 

T 

d 

t 

5 

$5 

enq 

nak 

% 

5 

E 

U 

e 

u 

6 

$6 

ack 

syn 

& 

6 

F 

V 

f 

V 

7 

$7 

bel 

etb 


7 

G 

W 

g 

w 

8 

$8 

bs 

can 

( 

8 

H 

X 

h 

X 

9 

$9 

ht 

em 

) 

9 

I 

Y 

i 

y 

10 

$A 

If 

sub 

• 


J 

Z 

j 

z 

11 

$B 

vt 

esc 

+ 

; 

K 

[ 

k 

{ 

12 

$C 

if 

fs 


< 

L 

\ 

1 

1 

13 

$D 

cr 

gs 

- 


M 

] 

m 

} 

14 

$E 

so 

rs 


> 

N 


n 

' 

15 

$F 

si 

us 

/ 

? 

0 


0 

rub 




9 

£ 


' CM 

rri 

■rr 


so 

r- 

00 

os 



V 

II 

A 

C^- 


a 



















» 




















p: 

s 


— c 








* 

+ 


1 





s 

S 

a. 

Q 

R 

uo 

H 


> 


X 

>- 

N 

- 

- 

- 

‘ 




2 

see 

@) 

< OQ 

U 

Q 

u 

u. 

0 

X 





s 

z 

0 


I 



















0 



















z 

>0 

S 

« 

— CN 



to 

so 


00 

Os 



V 

II 

A 





















It 





















1 

< 


- 0 

It 





W 


• 

+ 


1 






















08 



















It 

08 


? 


a. 

0 

R 

c /2 

H 

3 

> 


X 

>• 

N 



___ 

, 

1 

j: 

2 


















U 

c 

0 


















e 



s 


< oa 

U 

Q 

UJ 

u. 

0 

a: 



X 

tJ 

s 

Z 

0 

0 


g 


« 

— rs 

PO 


»o 

so 


00 

Os 



V 

II 

A 

e^. 




















u 

00 




- * 






-- 

-- 

* 

+ 


1 




1 


















< 

if 

£ 

£ 

0 . 

Q 

R 

C/2 

H 


> 


X 

>- 

N 

“ 


- 

‘ 

1 



S 

5 

(§) 

< OQ 

u 

Q 

U 

u. 

0 

X 

- 

- 

X 


s 

Z 

0 



9 

S 

« 

— CM 




so 

r~ 

00 

Os 



V 

« 

A 

C^- 


> 

S 

S 



41: 

6(9 

# 

< 


- 


* 

+ 


1 


- 


c 


s 

a. 

Q 

R 

c/2 

H 


> 


X 

> 

N 

- 

-- 

- 

‘ 

1 



* 

I 


< CQ 

U 

Q 

UJ 

u. 

0 

X 

- 

- 

X 


s 

Z 

0 




z 

S 

5? S 

s 

S 



u 

00 

S» 

< 

A 


Q 


ll 



loecimal 







nC 


90 









Keys and Their A 

ssociated AS< 

CII Codes 

Key 

Alone 

CTRL 

SHIFT 

Both 

Key 

Alone 

CTRL 

SHIFT 

Both 

space 

$A0 

SA0 

SA0 

SA0 

RETURN 

S8D 

S8D 

S8D 

S8D 

9 

SB0 

SB0 

SB0 

SB0 

G 

SC7 

S87 

SC7 

S87 

V. 

$B1 

SBl 

$A1 

SAl 

H 

SC8 

S88 

SC8 

S88 

r 

$B2 

SB2 

SA2 

SA2 

1 

SC9 

S89 

SC9 

S89 

3# 

$B3 

SB3 

SA3 

SA3 

J 

SCA 

S8A 

SCA 

S8A 

4$ 

$B4 

SB4 

SA4 

SA4 

K 

SCB 

S8B 

SCB 

S8B 

5% 

$B5 

SB5 

SA5 

SA5 

L 

see 

S8C 

see 

S8C 

6& 

$B6 

SB6 

SA6 

SA6 

M 

SCD 

S8D 

SDD 

S9D 

T 

$B7 

SB7 

SA7 

SA7 

N' 

SCE 

S8E 

SDE 

S9E 

8( 

$B8 

SB8 

SA8 

SA8 

0 

SCF 

S8F 

SCF 

S8F 

9) 

$B9 

SB9 

SA9 

SA9 

P@ 

SD0 

S90 

SC0 

S80 

;* 

$BA 

SBA 

SAA 

SAA 

Q 

SDl 

S91 

SDI 

S91 

; + 

$BB 

SBB 

SAB 

SAB 

R 

SD2 

S92 

SD2 

S92 

,< 

SAC 

SAC 

SBC 

SBC 

s 

SD3 

S93 

SD3 

S93 

- = 

SAD 

SAD 

SBD 

SBD 

T 

SD4 

S94 

SD4 

S94 

.> 

SAE 

SAE 

SBE 

SBE 

U 

SD5 

S95 

SD5 

S95 

/? 

SAF 

SAF 

SBF 

SBF 

V 

SD6 

S96 

SD6 

S96 

A 

SCI 

S81 

SCI 

S81 

W 

SD7 

S97 

SD7 

S97 

B 

SC2 

S82 

SC2 

S82 

X 

SD8 

S98 

SD8 

S98 

C 

SC3 

S83 

SC3 

S83 

Y 

SD9 

S99 

SD9 

S99 

D 

SC4 

S84 

SC4 

S84 

Z 

SDA 

S9A 

SDA 

S9A 

E 

SC5 

S85 

SC5 

S85 

— 

S88 

S88 

S88 

S88 

F 

SC6 

S86 

SC6 

S86 

— 

S95 

S95 

S95 

S95 






ESC 

S9B 

S9B 

S9B 

S9B 


RAM Organization and Usage 

Page Number: 
Decimal Hex 

Used For: 

0 $00 

System Programs 

I $01 

System Stack 

2 $02 

GETLN Input Buffer 

3 $03 

Monitor Vector Locations 

4 $04 

5 $05 

6 $06 

7 $07 

Text and Lo-Res Graphics 

Primary Page Storage 

8 $08 

9 $09 

10 $0A 

11 $0B 

Text and Lo-Res Graphics 
Secondary Page Storage 

FREE 

RAM 

12 $0C 

through 

31 $1F 


32 $20 

through 

63 $3F 

Hi-Res Graphics 

Primary Page 

Storage 

64 $40 

through 

95 $5F 

Hi-Res Graphics 

Secondary Page 

Storage 

96 $60 

through 

191 $BF 



















































Editor Commands 


Assembler Directives 


Macros 


i 


Control Commands 


CTRL A 

tab right 

CTRL B 

home to bottom of page 

CTRLC 

search and replace up 

CTRL D 

clear to end of line 

CTRL E 

home to end of line 

CTRL F 

home to top of file 

CTRLG 

shift display window 

CTRL 1 

toggle display 

CTRL K 

left bracket 

CTRL L 

home to end of file 

CTRL N 

switch return mode 

CTRLO 

shift lock 

CTRL P 

pop lines from buffer 

CTRLQ 

quit 

CTRL R 

remove blank lines 

CTRLS 

tab left 

CTRLT 

home to top of page 

CTRL V 

search and replace down 

CTRL W 

home to start of line 

CTRL X 

string search down 

CTRL Y 

switch cursor mode 

CTRLZ 

string search up 

leapt Commands 

[ESC] B 

insert a line 

[ESC] C 

scroll screen down 

[ESC] E 

scroll screen up 

(ESC] F 

display memory used 

[ESC] G 

delete a character 

[ESC] H 

insert a character 

[ESC] 1 

move cursor up 

[ESC] J 

move cursor left 

[ESC] K 

move cursor right 

[ESC] M 

move cursor down 

[ESC] 0 

delete lines to buffer 

[ESC] P 

copy lines to buffer 

[ESC] W 

scroll screen up one page 

[ESC] X 

scroll screen down one page 

[ESC] Y 

delete a line 

[ESC] * 

enter search string 

[ESC] ; 

enter replace string 

[ESC] -> 

Insert a character from the buffer 

[ESC] <- 

delete a character to the buffer 

[ESC] ! 

vertical bar 

[ESC] ( 

left curly bracket 

[ESC] ) 

right curly bracket 

[ESC] < 

left square bracket 

[ESC] > 

right square bracket 

[ESC] % 

at sign 

[ESC] " 

up arrow 

[ESC] / 

Backslash 

[ESC] _ 

Underline 

[ESC] + 

Tilde 


ACTR 

set assembler loop counter ! 

Floating Point (library and ROM) 


AIF 

conditional assembler branch 




AINPT 

assembler input 

ABS 

ADI 

absolute value 

AGO 

unconditional assembler branch 

ATAN 

AD1,AD2 

arc tangent 

AMID 

mid string function for symbolic parameters 

CHRGET 


character input initialization 

ANOP 

assembler no operation 

CHS 

ADI 

change sign 

APEND 

append a source file / 

COS 

AD1,AD2 

cosine 

ASRCH 

string search for symbolic parameters 

EXP 

AD1,AD2 

exponent 

COPY 

copy a source file 

FADD 

AD1,AD2,AD3 

add 

DATA 

start data area 

FDIVD 

AD1,AD2,AD3 

divide 

DC 

declare constant 

FERR 

ADR 

set floating point error 

DS 

declare storage 



(SUBS only) 

EJECT 

skip to new printer page 

FIX 

AD1,AD2 

convert to integer 

END 

end program segment 

FIX4 

AD1,AD2 

convert to 4 byte integer (SUBS only) 

EQU 

define symbolic constant 

FLOAT 

AD1,AD2 

convert to floating point 

ENTRY 

define entry point 

FLOAT4 

AD1,AD2 

convert 4 byte integer to 

ERROR 

print errors 



floating point (SUBS only) 

EXPND 

expand DC statements 

FMULT 

AD1,AD2,AD3 

multiply 

FPLEN 

set floating point length 

FPIN 

ADR,STRING 

input 

GBLA 

define global arithmetic symbolic parameter 

FPOUT 

ADI 

output 

GBLB 

define global boolean symbolic parameter 

FSUB 

AD1,AD2,AD3 

subtract 

GBLC 

define global character symbolic parameter 

INT 

AD1,AD2 

integer function 

GEN 

generate macro expansions 

LN 

AD1,AD2 

natural logarithm 

GEQU 

define global symbolic constant 

PWR 

AD1,AD2,AD3 

raise a number to a power 

KEEP 

keep object module 

RND 

ADI 

random number 

LCLA 

define local arithmetic symbolic parameter 

SIGN 

AD1,AD2 

sign function 

LCLB 

define local boolean symbolic parameter 

SIN 

AD1,AD2 

sine 

LCLC 

define local character symbolic parameter 

SQR 

AD1,AD2 

square root 

LIST 

list output 

TAN 

AD1,AD2 

tangent 

MCOPY 

copy macro file 




MDROP 

drop macro file • 




MEM 

reserve memory range 




MERR 

maximum error level 




MLOAD 

load macro file 




MNOTE 

MSB 

macro note (error statement) 
set most significant bit 

Integer Mathematics 



ORG set origin 

PAGE skip to page boundary 

PRNT sent output to the printer 

SETA set arithmetic symbolic parameter 

SETB set boolean symbolic parameter 

SETC set character symbolic parameter 

START start subroutine 

SYMBL print symbol tables 

TITLE set page headers 

USING using data area 

The following directives are only valid inside of a macro file. 


MACRO 

MEND 

MEXIT 


Start macro 
end macro 
exit macro 


ADD 

AD1,AD2,AD3 

two byte integer add 

ADD4 

AD1,AD2,AD3 

four byte integer add 

CNV24 

12,14 

convert two byte to four byte 

CNV42 

14,12 

convert four byte to two byte 

DIVD 

AD1,AD2,AD3 

two byte Integer divide 

DIV4 

AD1,AD2,AD3 

four byte integer divide 

lABS 

ADI 

two byte integer absolute value 

IIN 

ADI,STRING 

two byte integer input 

lOUT 

ADI 

two byte integer output 

ISIGN 

ADI 

two byte integer sign function 

ISQR 

AD1,AD2 

two byte integer square root 

I4ABS 

ADI 

four byte integer absolute value 

I4IN 

ADI,STRING 

four byte integer input 

I40UT 

ADI 

four byte integer output 

I4SIGN 

AD1,AD2 

four byte integer sign function 

I4SQR 

AD1,AD2 

four byte integer square root 

MOD 

AD1,AD2,AD3 

two byte modulo function 

M0D4 

AD1,AD2,AD3 

four byte modulo function 

MULT 

AD1,AD2,AD3 

two byte integer multiply 

MUL4 

AD1,AD2,AD3 

four byte integer multiply 

SUB 

AD1,AD2,AD3 

two byte integer subtract 

SUB4 

AD1,AD2,AD3 

four byte Integer subtract 











Double Precision Floating Point 


Logic and Branching 


CNVDF 

DP,FP 

CNVFD 

FP,DP 

DABS 

ADI 

DADD 

AD1,AD2,AD3 

DATAN 

AD1,AD2 

DCHS 

ADI 

DCOS 

AD1,AD2 

DDIVD 

AD1,AD2,AD3 

DEXP 

ADl^ADE 

DFIX 

AD1,AD2 

DFIX4 

AD1,AD2 

DFLOAT 

AD1,AD2 

DFL0AT4 

AD1,AD2 

DINT 

AD1,AD2 

DLN 

AD1,AD2 

DMULT . 

AD1,AD2,AD3 

DPIN 

ADR,STRING 

DPOUT 

ADI 

DPWR 

AD1,AD2,AD3 

DRND 


DSIGN 

AD1,AD2 

DSIN 

AD1,AD2 

DSQR 

AD1,AD2 

DSUB 

AD1,AD2,AD3 

DTAN 

AD1,AD2 


Input and Output 

COUT 

R,C 

CROUT 

C 

FLASH 


GETLN 

WRD 

HOME 


HTAB 

NUM 

INPUT 

CHRS 

INVERSE 


NORMAL 


PRAX 


PRBL 

NUM 

PRBYTE 

ADR 

PRERR 


PRHEX 

ADR 

PRINT 

CHRS 

PRINTC 

CHRS 

PRINT2 

CHRS 

PRNUM 


PROMPT 

CHAR 

RDKEY 

CRS 

VTAB 

NUM 

WNDB 

NUM 

WNDL 

NUM 

WNDT 

NUM 

WNDW 

NUM 

WRITE 

CHRS,NUM 

WRITEC 

CHRS,NUM 

WRITE2 

CHRS,NUM 


convert double precision to 
single precision 
convert single precision to 
double precision 
absolute value 
add 

tangent 

change sign 

cosine 

divide 

exponent 

convert to integer 

convert to 4 byte Integer 

convert from integer 

convert from 4 byte integer 

integer function 

natural logarithm 

multiply 

input 

output 

raise a number to a power 

random number 

sign function 

sine function 

square root 

subtract 

tangent 


write character 
issue return 
set flashing characters 
get a line 

clear screen and home 
cursor 

horizontal tab 
input with prompt 
set inverse characters 
set normal characters 
print A.X as hex number 
print blanks 

print accumulator in hex 

print ’ERR’ 

print a hex digit 

print characters with return 

print centered characters 

print characters without 

return 

print number string 

set prompt character 

read a character 

vertical tab 

set window bottom 

set window left 

set window top 

set window width 

write characters with return 

write centered characters 

write characters without 

return 


ASL2 

ADR 

BGT 

BP 

BLE 

BP 

CMP2 

AD1,AD2,R 

DBNE 

R,BP 

DBNE2 

ADR,BP,R 

DBPL 

R,BP 

DEC2 

AD1,R 

INC2 

ADR 

JCC 

BP 

JCS 

BP 

JEQ 

BP 

JGE 

BP 

JGT 

BP 

JLE 

BP 

JLT 

BP 

JMI 

BP 

JNE 

BP 

JPL 

BP 

LSR2 

ADR 

MASL 

ADR,NUM 

MLSR 

ADR,NUM 


Miscellaneous Macros 


BELL 

BUTON 

BTN,VAL 

DW 

ADR 

LA 

AD1,AD2,R 

LM 

AD1,AD2,R 

MOVE 

AD1,AD2,L,R 

PAGEl 

PAGE2 

PREAD 

RESTORE 

SAVE 

TEXT 

WAIT 

CNT 


Low Resolution Graphics 


CLRGR 

ALL 

COLOR 


GR 


GREAD 

X,Y 

HLINE 

X1,X2,Y 

PLOT 

X,Y 

VLINE 

X,Yl,y2 


High Resolution Graphics 

HCLEAR 
HCOLOR 
HDRAW X,Y 

HGR ALL 

HPAGE PAGE 

HPLOT X,Y 

HPOSN X,Y 


Attributes 


two byte arithmetic shift left 
branch if greater than 
branch if less than or equal 
two byte unsigned compare 
decrement and branch not equal 
two byte decrement 
and branch not equal 
decrement and branch if plus 
two byte decrement 
two byte Increment 
jump if carry clear 
jump if carry set 
jump if equal 

jump if greater than or equal 

jump if greater than 

jump if less than or equal 

jump if less than 

jump if minus 

jump if not equal 

jump if plus 

two byte logical shift right 
multiple arithmetic shift left 
multiple logical shift right 


sound apple bell 
read a button 
define a word 
load address 
load memory 
move memory 
set display to page 1 
set display to page 2 
PDL.VAL read a paddle 
restore registers 
save registers 
display text 
pause for a while 


i 

f 


I Character Meaning 

A Address Type DC Directive 

B Booleaxx Type DC Directive 

C Character Type DC Directive 

D Double Precision Floating Point Type DC Directive 

F Floating Point Type DC Directive 

G EQU or GEQU Directive 

H Hexadecimal Type DC Directive 

I 2 Byte Integer Type DC Directive 

J 4 Byte Integer Type DC Directive 

K Reference Address Type DC Directive 

L Soft Reference Type DC Directive 

! M Instruction 

! N Assembler Directive 

0 ORG Directive 

P PAGE Directive 

R 1 Byte Integer Type DC Directive 

S DS Directive 

X Arithmetic Symbolic Parameter 

Y Boolean Symbolic Parameter 

Z Character Symbolic Parameter 


clear screen 
C set color 

ALL set display to low res 
graphics 

read graphics screen 
draw horizontal line 
plot a point 
draw vertical line 


clear graphics page 
C set color 
draw a Ine 

display high res graphics 
set the page to draw on 
plot high res point 
position the cursor 



T 

C 

L 

LABEL 

See 

table 

1 if 

defined 

No. bytes 
generated 

ARITH 

X 

No. of 
subscripts 

2 

BOOLEAN 

Y 

No. of 
subscripts 

1 

CHAR 

z 

No. of 
subscripts 

Length of 
string 

















(KCAM 


The Assembler 

Macro Language Features: 

• Conditional assembly of source and 
macro files 

• Separate source and macro files 

• Nestable macros 

• Parameter mid-string and search 

• Paramter assignment 

• Numeric, string and boolean types 

• Paramter subscripting 

• Global communications between macros 

• Macro expansion loop control 

• Count, Length and Type attributes 
Extensive Macro Libraries 

• Includes hi-res graphics macros 
Relocatable Object Modules 
Supports 65C02 instruction set 
Fast Assembly to Disk 

Program Segmentation 

• Selectively assembles individual sub¬ 
routines 

• Global and Local scope of symbols 
The Linker 

Produces executable binary from re¬ 
locatable files 

Link routines from library files 

Link subroutine re-assemblies 

Define a new origin for previously 
assembled code 

Invoke at assembly time or by command 
Subroutine Libraries: 

• Single and double precision floating 
point 

• Transcendental functions 

• Multiple-precision integers 

• Input and Dutput 


The Editor 

Co-resident screen editor: 

• Global search and replace 

• Block move 

• Eighty column display or forty column 
with horizontal scrolling 

The System 

Transparent control of system from one 

command level 

Extended disk commands: 

• File copy 

• File undelete 

• Catalog sort 

• Wildcard filenames 

Disk ZAP sector editor 

Dptimized DDS 3.3 compatible operating 

system. 

Dperating System Interface: 

• Supports a variety of configurations 

• User-modifiable to allow linkage of 
custom drivers for peripherals 

• Drivers included for 128K card and //e 
or lie disk emulator, lie and lie 
eighty-column card, Videx and Wizard- 
8D eighty-column cards, CCS, CPS, 
Prometheus and Thunderclock clock 
cards 

64K, 128K RAM supported; 48K required 



SOFTWARE 


NEW! DRCA/M Utilities 

The DRCA/M Utilities included in this 
package is a set of program development 
tools for use with the DRCA/M 65D2 
Assembler. It contains six programs: 

MDN+ is a debugging tool for DRCA which 
includes powerfu' memory manipulation 
commands, a mini-assembler, a step and 
trace command, th( ability to set break¬ 
points, and a symbol table. 

XREF scans a source file stream and 
generates a cross-reference listing of 
all of the symbols used in the program, 
indicating the line where the symbol was 
first defined,and the line numbers of 
all references. 

DISASM is a disassembler which produces 
source files in an DRCA compatible 
format. It is a highly interactive 
program, allowing the program to be 
disassembled layer by layer. 

MACGEN eliminates the inefficiency 
and/or tedium of dealing with programs 
using many macros from different library 
files. It scans a source file stream and 
builds a list of the macros used, from 
which a new macro library file can easily 
be created. 

INCDVER is a disk initialize/copy 
program that can be executed from within 
the DRCA environment. It also has a 
verify option, allowing two disks to be 
compared for confirmation that they are 
identical. 

CRUNCH is a time- and space-saving 
utility which takes the various 
generations of object modules that 
result from repeated partial assembly, 
and compacts them into a single file, and 
deletes the left-over files. 
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Reference Manual Addendum 
for ORCA/M version 3.5 

Introduction 

ORCA 3.5 includes several new features, support for additional hardware, and fixes for 
bugs found in the original release. This document describes those new features which 
are not included in the original 3.4 reference manual. The other changes—program 
fixes and additional hardware suported—are described in the ORCA System Technical 
Bulletins #1 and #3, respectively. 

With a few exceptions, all of the files on the 3.5 disks existed in version 3.4. The most 
notable exception is the file O/S EXTENSION, an expansion of the O/S allowing one of 
the 4K banks on a 16K RAM card to be used as additional operating system memory. 
This file must reside on the system disk if oneof the configuration options requiringthe 
additional memory is selected, such as the Apple //e 80 column board. It is not needed 
for the standard, default configuration. The source code for the extension consists of 
five files found on disk two (volume 101, SYSTEM SOURCE). Their filenames begin with 
OS. 

Because there are more files contained in the system, It is now provided on four 
diskettes. The fourth, not described in the 3.4 manual, is volume 103, MACLIB 
SOURCE. All of the macro libraries are now found on this disk; volume 101, SYSTEM 
SOURCE, contains only the operating system source code. 

Two new macro files are provided to support the op codes found on the Rockwell 
version of the new 65C02 processor. These are called MACLIB.65C02 and 
MACLIB.65C02.BBR. The standard 66C02 Instruction set Itself is supported by the 
assembler, as described below. 
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The 3.5 system is configured in the same way as 3.4, that is, by re-assembling the 
operating system. Before doing this, be sure to refer to the hardware options bulletin 
provided with the system. In addition to listing the hardware supprted with specific 
operating system drivers, it also details the possible responses to the configuration 
option prompts which are displayed during re-assembly of the operating system. 

The Operating System 

The main change in the operating system is Its optional extension into the second 4K 
bank of a 16K RAM card (or bank-switched memory as It is called on the //e). 

This extension is required in several cases; for example, to support the Apple //e 80 
column board. The //e 80 column firmware as implemented by Apple was not readily 
compatible with the ORCA system, so it was necessary to re-write the support routines. 

If options are selected which require that this additional memory be used, the file O/S 
EXTENSION will be needed to boot the operating system in addition to the file ORCA 
O/S. When configured in this way, the RWTS routine is relocated Into the extension, as 
are the multiply/divide routines. This relocation frees up a considerable amount of 
memory in the standard O/S memory range of $B000-$BFFF. The memory thus made 
available may be used for larger custom drivers and USER commands. To force this 
relocation during assembly of the operating system in order to accomodate user- 
written drivers, simply set the global variable OSEXTF to TRUE when assembling the 
COMMON data area. 

Although the source code Is provided for it, it is expected that it will not be neccessary to 
re-assemble the extension itself; to use it, simply place it on the boot disk where it will be 
loaded automatically by the operating system. 

Whenever the extension is used, memory in the range $BF00-$BFFF must be kept free 
of code; It Is reserved for I/O buffers used by the extension when loading files into the 
language card. 

A few other changes were required to the operating system as a whole to manage the 
extension. The only one which effects standard (48K) systems is a change to the SPROF 
subroutine, setting the window width to the number of columns, instead of 40. 

Another new feature of the operating system is that disk read and write calls will return 
an error if a drive which has not been identified to the operating system during 
configuration is referenced. 

To accomodate non-standard volume sizes as found on 40-, 70-, and 80-track disks, as 
well as hard disks, a new system call named SHOOK has been added to the operating 
system. This allows virtually any disk that uses 256 byte sectors to be used with the 
system. The rest of the system vectors disk requeststhrough thissubroutineforspecial 
handling. If the carry flag is clear on return, the request is handled In the normal way. 
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User written drivers for non-standard disk devices can intercept these functions and 
provide routines to do the specified tasks. If the carry flag is set on return, then the 
calling program (i. e., the assembler, link editor, or monitor) will not perform the 
function; instead, it assumes that it has already been performed by the user driver. 


On entry to the subroutine, the X register contains a number indicating the type of 

request. Other inputs vary by the type of request, as listed below. 

1 : SVOLC; check for volume. The A register contains the number of the volume about 
to be searched for. The SLOT and DRIVE variables in the operating system contain 
the device that will be searched. If hard disks that map several standard apple format 
disks onto the same device are used, the subroutine must locate the proper disk and 
set appropriate flags so that further requests to that device “see” the proper volume. 

2: SVTOC; save VTOC. The system will save track 17, sector 0. If more that one sector Is 
used as a VTOC (e.g., on double sided disks) then the subroutine should take this 
opportunity to save the other sectors. The active device numbers are in the operating 
system variables SLOT and DRIVE. 

3: SRVTC; read VTOC. The system will load track 17, sector 0. If more than one sector 
is used for the VTOC, the subroutine should load those sectors into Its own buffer. 
The active device numbers are in the operating system variables SLOT and DRIVE. 

4: SFNTS; find a track/sector. The system is about to look for an empty disk sector. If a 
non-standard VTOC format is being used, (standard is 16 sectors on 35 to 40 tracks 
in the normal DOS 3.3 format) this function must locate a free sector when called. If 
there are none, return with the carry flag clear. If one is found, reserve it in the VTOC 
and return the track number In $000E and the sector number in $000D. 

5: SCHEK; Check to see if a sector is in use. If used, return zero in the accumulator; if 
not, return $FF. The track number should be in the accumulator and the sector 
number in the Y register when the routine is called. 

6: SCATL; catalog the disk. The disk is being cataloged, and the system needs to know 
how full it Is. If a non-standard VTOC is being used, set the carry flag and return the 
number of free sectors in $000C, and the percentage of the disk that has been used in 
$0000 (both are two byte integers). 

7: SRELS; release a sector. With a non-standard VTOC, set the carry flag and release 
the sector whose track number is in the accumulator and whose sector number is in 
the Y register. 

8: SCLAM; claim a sector. If the VTOC Is non-standard, set the carry flag and claim the 
sector whose track number Is in the accumulator and whose sector number is in the 
Y register. 




4 


ORCA/M 


There are a few notes in order about general considerations in using these hooks. First, 
if the call Is not being Intercepted, be sure and return with all registers intact and the 
carry flag clear. A non-standard VTOC must have at least a portion of the VTOC at track 
17, sector 0, with the standard format for the first $38 bytes. A full disk should leave the 
remainder of this track as zeros. Standard DOS file formats with normal track sector 
lists must be used. 

It is likely that 64K of memory will be required to allow use of the extension so as to have 
enough room in the operating system to add the appropriate driver routines. 

Finally, these hooks are still experimental. They are provided to support hardware 
which, by definition, has not yet been implemented with the system. For this reason, 
there may be software problems when interfacing with a particular piece of hardware. 
For an example of their use, look at the implementation of the 70-track Micro-ScI 
routines. 

As multiple languages are added to the system, the 140K available on a standard disk 
will not be large enough to accommodate all of the compilers, assemblers and 
subroutine libraries. In that case. It might be desirable to be able to change the system 
disk. All requests for the system disk are made by the FOPRS subroutine In the 
operating system, and refer to the system slot, drive and boot slot, drive variables in the 
COMMON area. Therefore, a routine could now change the system slot by simply 
changing the values at these locations. Both the system slot and the boot slot are 
searched. In that order, for system files. Among other things, this allows disk emulators 
to be used as the system disk. 

If a conflict develops in the implementation of a driver for a given piece of hardware, 
contact the publisher. The ORCA operating system is intended to be general enough to 
interface with any hardware that can normally interface with Apple DOS. Hayden 
Software will act as a clearinghouse for new support routines as they are developed. As 
these new user- or vendor-written routines become available, they will be incorporated 
into the ORCA operating system and made generally available in the form of technical 
bulletins. 

The Monitor and Text Editor 

Installed Devices 

If a disk slot and volume Is referenced from the monitor which has not been Identified to 
the operating system during the configuration process, a Device not Available error will 
result. 
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Keyboard Layouts 

Based on a value set during configuration of the operating system, the ORCA 3.5 
monitor will recognize different keyboard layouts for editing commands (and some 
monitor commands). The following table shows which keys do what with the different 
keyboard choices: 


Function 

Apple II 

Apple //e 


Franklin 

move up 

ESC I 

up arrow or 

ESC I 

ESC I 

move down 

ESC M 

down arrow 

ESC M 

or 

ESC M 

delete char 

ESC O 

DELETE 


ESC O 

restore char 

ESC ^=0 

open Apple 
DELETE 


ESC ^ 

tab right 

CTRL A 

TAB 


TAB 

tab left 

shift lock 

toggle display 

CTRL S 

CTRL 0 

CTRL I 

CTRL S or 
open Apple 

TAB 

CTRL S 

left bracket 

CTRL K 

[ 


[ 

move left 
(escape mode) 

ESC J 

O or ESC 

J 

ESC J 

move right 
(escape mode) 

ESC K 

'=> or ESC 

K 

ESC K 


Some additional keyboard-related changes have been made. ESC commands will now 
accept lower-case letters, as will any other system command. When using the Apple//e 
(with its four cursor movement keys), these keys move the cursor when the monitor 
PEEK command is used (and in fact thecontrol keysl, J,K and M are no longer valid for 
this purpose on the //e). 
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The Insert Mode 

A new mode has been added to the text editor, the insert mode. It is entered by hitting 
the ESC key twice. The first time ESC is keyed, the normal escape mode Is entered. 
Thus, the ESC key now toggles between the three editor modes. While in the insert 
mode, typed characters are inserted at the cursor location, and the line from the cursor 
to the end of the line Is moved forward one character to make room for the new 
character. Note that characters scrolled off the end of the line are lost. To exit the insert 
mode, hit the ESC key. Other insert mode command keys are listed below. 

ESC Exits the insert mode. 

TAB Inserts blanks until the cursor gets to the next tab stop. CTRL A is used 

on keyboards that do not have a TAB key. 

<=1 The character to the left of the cursor Is deleted to the character buffer, 

and the rest of the line is moved one space to the left. If this isdoneatthe 
beginning of a line, the line is deleted, and all characters that were on the 
line are appended to the line above. 

f=> The last character deleted is inserted at the cursor location. An end of 

line that is un-deleted splits the current line, creating a new line 
containing the characters from the cursor position to the end of the line. 

RETURN This splits the line at the cursor position, creating a new line to hold the 
characters from the cursor to the end of the line. 


Note that the left and right arrow function the same way In both the escape and insert 
mode. Also note that the way the left and right arrow (or DELETE aand open apple 
DELETE on the//e) work has changed slightly—before, deletions at the beginning of 
the line were ignored; now, the “carriage return” represented by the beginning of the 
line is deleted, combining the two lines. 

In version 3.4, an non-keyboard ASCII character was missing—it was not possible to 
enter the left single quote mark (‘) from the Apple II keyboard. This can now be entered 
by typing the standard single quote mark (’) from the escape mode. 

A new option has been added to the possible answers for file name prompts. Whenever 
the wildcard Is used in a file name and prompting is selected, a third option Is available 
in addition to Y or N (for Yes or No): Q for Quit. 

Assembler 

Four additions have been made to the 3.5 version of the assembler. The first is a 
message at the end of each assembly telling how many macros were expanded. 
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The second is an important addition to the macro language. A special symbolic 
parameter, &SYSOPR, is now available. When used, It should be the only symbolic 
parameter in the macro definition statement. On resolution the entire operand field of 
the macro call statement is placed in &SYSOPR, regardless of punctuation. The 
operand can then be parsed In the macro using the conditional assembly language. For 
example, the macro 

MACRO 

TEST &SYSOPR 
! &SYSOPR 
MEND 

called by the macro call statement 

TEST AN OPERAND WITH SPACES 
from the source program would generate the comment 
+! AN OPERAND WITH SPACES 

Other punctuation, such as equal signs and parentheses, are also ignored. Two uses are 
envisioned for this capability. The first is for operands whose format might be 
misinterpreted by the macro language, such as indirect addresses. The second is for 
free format macros, such as structured statements. Using this capability, it should be 
possible to define a primitive, albeit slow, BASIC compiler entirely with macros. 

Limited support for the proposed IEEE floating point standard has been added. By 
coding the directive 

IEEE ON 

the floating point format for floating point DC statements uses the format of the 
proposed standard. Note, however, that none of the library routines currently support 
this format; it Is included In anticipation of high-level languages that will use this format. 

The last addition to the assembler is support for the new W65SC02 CPU, designed by 
the Western Design Center, Inc. The 65C02 is an enhanced, pin compatible CMCS 
replacement for the original NMCS 6502. The chip is currently available in two versions, 
one from GTE Microcircuits and NCR, and another from Rockwell I nternatlonal. Cther 
manufacturers will be producing the GTE/NCR version soon. (The Rockwell chip 
Includes special additional instructions for page zero bit manipulation.) The GTE chip 
has been successfully tested In both the Apple II and Apple//e, although there rema/ns 
the possibility of incompatability with some revisions of the Apple II. To enable the 
extended instruction set, code the directive 


66C03 ON 
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The same directive may be used with the operand of OFF to disable the extension, in 
which case the new instructions and addressing modes will be treated as errors. The bit- 
manipulation instructions of the Rockwell chip— RMBx, SMBx, BBRx and BBSx— are 
not a part of the basic 65C02 design, and since they will not be supported by the Western 
Design Center in future upgrades, they are not included in the assembler. I nstead, these 
Instructions are provided as macros In the files MACLIB.65C02 and MACLIB.65C02.BBR. 

There are three new addressing modes. Many old instructions now support a true 
Indirect addressing mode, coded with a zero page address enclosed In parentheses: 

ORA (ZP) 

The zero page address points to a two byte effective address. This is equivalent to 
either: 


ORA (ZP,X) 

ORA (ZP),Y 

if the X and Y registers had zero in them. The JMP instruction has an absolute Indexed 
indirect addressing mode, coded as 

JMP (ABS,X) 

This works exactly like the old addressing mode that took the same format, but it is not 
limited to zero page addresses. Finally, the BBRx and BBSx instructions found in the 
Rockwell implementation use a combination of zero page and relative addressing. They 
perform bit tests on zero page addresses, followed by a conditional branch in the same 
instruction. This is coded as 

BBR5 ZP,ABS 

which would branch to ABS if bit 5 of ZP were 0. 

The new instructions and addressing modes are described In the supplement to 
Appendix B, The 65C02 Instruction Set. 

Link Editor 

The link editor in version 3.5 will now take advantage of the RAM card, using it for the 
symbol table. This doubles its maximum size; the link editor can now handle over 1000 
global labels. 

Also, the way symbol tables are handled has been completely reworked in version 3.5, 
resulting In an overall speed inprovement of about 15%. This change will probably not 
be noticeable on small programs but has been measured at up to 25% on very long ones 
(about 14000 lines). 
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Macro and Subroutine Libraries 

The random number macros were undocumented in the 3.4 manual. These consist of a 
set of four macros which generate random numbers in the four number formats 
supported by ORCA. The operand in each case is the address of the number to be 
randomized. Integer random numbers can span the range of Integers for the specified 
length, while floating point random numbers range from 0.0 to 1.0, including 0.0 but 
excluding 1.0 (in other words, the range Is 0.0 to 0.9999 ... with as many nines as the 
precision of the number allows). All four macros are initialized with the SEED macro. 
The SEED macro need only be coded once, and must be coded before the first use of 
any of the random number macros. The operand points to a two byte seed value. If the 
operand Is omitted, the seed which the Apple automatically sets while it waits for 
keyboard Inputs is used. Normally, that is the best seed available. One exception is 
during debugging, when a duplicate seed at each program execution will yield Identical 
sequences of random numbers. The random number macros require the subroutine 


library. 



macro 


description 

IRND 

ADR 

two byte random number 

I4RND 

ADR 

four byte random number 

FRND 

ADR 

floating point random number 

DRND 

ADR 

double precision random number 

SEED 

ADR 

seed the random number generator 


Appendix B Supplement: 

The 65C02 Instruction Set 

Branching Instructions 

BRA - Branch Always 

Branch unconditionally. None of the flags are tested; BRA is used as a “quick” jump 
within the range of the relative offset. It only requires two bytes (opcode and offset), 
rather than the three bytes an absolute JMP instruction uses. 


Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles Form 

Relative 

80 

2 

3* BRA ABS 
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Implied Operand Instructions 

PHX - Push X 

The X register is pushed onto the stack. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Implied 

DA 

1 

4 

PHX 

PHY - Push Y 





The Y register is pushed onto the stack. 


Flags Modified: 

none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Implied 

5A 

1 

4 

PHY 


PLX - Pull X 

TheX register is pulled from the stack. UnlikethePLA Instruction, no flags are effected. 
Flags Modified: None 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

FA 

1 

4 PLX 


PLY - Pull Y 

The Y register Is pulled from the stack. UnlikethePLA Instruction, no flags are effected. 
Flags Modified: None 

Addressing Hex Bytes Cycles Form 

Implied 7A 1 4 PLY 
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Load and Store Instructions 

STZ - Store Zero 

The specified memory location is cleared, that is, a zero is stored to it. 
Flags Modified: None 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

9C 

3 

4 

STZ 

ABS 

Zero Page 

64 

2 

3 

STZ 

ZP 

Absolute,X 

9E 

3 

6 

STZ 

ABS,X 

Zero Page,X 

74 

2 

4 

STZ 

ZP,X 


Logical and Arithmetic Instructions 

TRB - Test and Reset Bits 

This instruction performs a logical AND of the complement of the accumulator and the 
specified memory location, and stores the result In the specified memory location. 

Flags Modified: Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Absolute 

1C 

3 

4 

TRB ABS 

Zero Page 

14 

2 

3 

TRB ZP 


TSB - Test and Set Bits 

This instruction performs a logical OR of the accumulator and the specified memory 
location, and stores the result in the specified memory location. 

Flags Modified: Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Absolute 

oc 

3 

4 

TSB ABS 

Zero Page 

04 

2 

3 

TSB ZP 
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New Addressing Modes for Old Instructions 

LDA - Load Accumulator 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Indirect 

B2 

2 

5 

LDA 

(ZP) 

STA - Store Accumulator 





Flags Modified: none 



Addressing 

Hex 

Bytes 

Cycles 

Form 


Indirect 

92 

2 

6 

STA 

(ZP) 

JMP - Jump 






Flags Modified: N 

V Z 



Addressing 

Hex 

Bytes 

Cycles 

Form 


(Indirect,X) 

7C 

3 

6 

JMP 

(ABS 

ADC - Add With Carry 





Flags Modified: N 

V Z C 



Addressing 

Hex 

Bytes 

Cycles 

Form 


Indirect 

72 

2 

6 

ADC 

(ZP) 

AND - Logical AND 





Flags Modified: N 

Z 



Addressing 

Hex 

Bytes 

Cycles 

Form 


Indirect 

32 

2 

5 

AND 

(ZP) 
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BIT - Compare Memory and Accumulator 

Flags Modified: N V Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Immediate 

89 

2 

2 

BIT 

#ZP 

Absolute,X 

3C 

3 

4 

BIT 

ABS,X 

Indirect 

34 

2 

4 

BIT 

ZP,X 


CMP - Compare Accumulator and Memory 


Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Indirect 

D2 

2 

5 

CMP 

(ZP) 





CPA 

(ZP) 


DEC - Decrement Memory or Accumulator 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Accumulator 

3A 

1 

2 

DEA 


EOR - Exclusive OR with Accumulator 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Indirect 

52 

2 

6 

EOR 

(ZP) 


INC - Increment Memory or Accumulator 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Accumulator 

lA 

1 

2 

INA A 
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ORA - Inclusive OR with Accumulator 
Flags Modified: N Z 

Addressing Hex Bytes Cycles Form 

Indirect 12 2 6 ORA (ZP) 

SBC - Subtract with Carry 

Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles Form 


Indirect 

F2 

2 

6 SBC 

(ZP) 


HAYDEN SOFTWARE COMPANY 
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ORCA System Technical Bulletin #1: 


Program Errors in the 3.4 System 


Introduction 


The following is a description of the program errors discovered in the ORCA/M 3.4 
System as of June, 1983. Errors discovered as of that date are corrected in the 3.5 
release of the same month. 

Items are grouped according to the program affected. 


The Monitor 

The monitor COPY command did not convert lower-case to upper-case in filenames. 

ESC mode commands in the editor would not accept lower-case. 

TAB sometimes misplaced the cursor in forty column mode. Likewise, CTRL-R in the 
PEEK command would also misplace the cursor, again in forty column mode. 

Finally, the PEEK command would accept 16 as a valid sector number. 


The Assembler 


There are eleven known bugs In the 3.4 version of the assembler. The first Involves the 
protocol for switching between multiple languages. Since this capability has never 
been used, and since the error is quite involved, simply note that version 3.5 (or later) 
must be used with multiple languages, such as the forthcoming ORCA Pascal. 
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The second involved the use of multiple repeat counts with a single DC statement. The 
second (and later) repeated constant used the first constant for the repeat. For example, 
the statement 

DC 8H»00»,8H»80» 

would resolve as eight OO’s, an 80, and seven more OO’s. It should resolve as eight OO’s 
followed by eight 80’s. 

Third, square brackets surrounding a label name gave an error, instead of forcing the 
assembler to treat the label as zero page as specified in the program documentation. 

If an initial apostrophe was used to delimit a file name used as an operand for a directive 
(such as MCOPY ), the lack of a closing apostrophe would hang the system. An error 
message is now displayed. 

If volume numbers were not specified with file names used as the operands of assembly 
directives such as KEEP and MCOPY, the resulting default condition could result in 
incorrect information being written to the VTOC on a multiple drive system. While this 
has been corrected, good style dictates that volume specifications should always follow 
file names within a source file. 

COPY would not work correctly in certain circumstances; this has been corrected. 

Unresolved labels in MEM directives did not give an error, as they should. 

Floating point DC statements consisting of exact inverse powers of 2, e. g., 0.5, 0.25, 
0.125, evaluated Incorrectly (they were off by a factor of 2). 

Relative branches used after a PAGE directive could result in an incorrect 8ranc/7 0 L/f of 
range error during link editing. 

If a macro library was not found, it could result in a system crash. 

The final error is that the DC statement does not allow labels (other than constants 
defined with equate statements) in one byte integer constants. Although it was never 
designed to have that capability, error handling for the condition was also Inadequate, 
normally resulting In a strange link editor error. Labels can now be used, but only for 
defining a single byte—the repeat count, the ability to mix DC types, and the ability to 
define more than one byte on a single line are lost when labels are used. This restriction 
does not apply to constants defined with an equate statement. 
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Link Editor 

Seven bugs are known in version 3.4 of the link editor. The first is that the automatically 
defined label LOMEM was set before subroutine libraries were searched, placing it at 
the end of user code, but at the beginning of library routines. It Is now placed at the end 
of the entire program. 

The second occurs when a START and ENTRY directive have the same name and value, 
and are coded in the same subroutine. The resulting code Is correct, but If any ENTRY 
directives follow the duplicate one, the link editor would insist on searching the 
subroutine libraries at the end of pass 2, whether or not they were needed at the end of 
pass 1. 

DC ’R’ type references which were not resolved did not generate error messages and 
could produce spurious data within the gernerated object code. 

Having the .ROOT file and a SUBLIB file on different disks on a single drive system 
resulted In damaging disk I/O errors. 

A SUBLIB file was not searched If It was the first file In a catalog. 

It was possible for subroutine library searches to look for invalid slot/drive 
combinations. 

Finally, ‘S’ type DC references were resolved whether or not they were referenced 
elsewhere. They should be resolved only if some other reference was made to the 
address they reference. 

Macro and Subroutine Libraries 

It was discovered that use of the floating point add macros without the subtract macros, 
or of the sine macros without the cosine macros, could result In unresolved external 
references. This is due to the fact that add is an entry point in the subtract subroutine, 
and sine Is an entry point in the cosine subroutine. Macros and subroutines now have ’R’ 
type references where needed to force Inclusion of the proper subroutines. 

The macro LSR2, which was described in the manual, was not included in the 

MACLIB.LOGIC file. 

Convert 

If the CONVERT utility was used to convert a file from one disk onto another, the VTOC 
was not always updated correctly. 



HAYDEN SOFTWARE COMPANY 

600 Suffolk Street, Lowell MA 01853 

Copyright © 1983 by Hayden Book Company, Inc. 



ORCA System Technical Bulletin #2 


The 3.5 Update 


Introduction 


To allow users of the original ORCA/M 3.4 programto upgrade their systems to version 
3.5, the 3.5 update kit is being made available. 

The 3.5 upgrade kit consists of the following: 

2 Update diskettes (or one double sided disk) 

Orca Version 3.6 Documentation Addendum 
Technical Bulletin #1: 3.4 Program Errors 
Technical Bulletin #2: The 3.5 Update 
Technical Bulletin #3: 3.5 Hardware Options 

The update diskettes contain copies of all the additional files and files that have 
changed in version 3.5. The documentation addendum describes the differences 
between version 3.4 and 3.5 and is an update of the 3.4 documentation. 

Technical Bulletin #1 details all of the bugs and/or problems encountered In 3.4, and 
how they were addressed by the 3.5 system. 

Technical Bulletin #2 is this document. 

Technical Bulletin #3 describes the hardware options available atthetime of 3.5 release 
and describes the configuration procedure. This replaces the source file OPTIONS as 
found on the 3.4 systems and as described in the 3.4 documentation. 
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Installing the 3.5 Update 


One feature of 3.5 is that there are more files provided with the system; this has 
neccessitated the addition of another volume to the system, volume 103, MACLIB 
SOURCE. This contains all of the library macros that used to be found on volume 101. 
Volume 101, SYSTEM SOURCE, now consists of operating system source code only, 
including source code for the new O/S EXTENSION. 

The recommended procedure for Installing 3.5 Is to create the same configuration as 3.5 
is currently being distributed in. 

Begin by making fresh back-up copies of the original 3.4 system disks—volumes 100, 
101, and 102. A fourth, initialized blank disk will also be needed—it should be Initialized 
as volume 103. These disks will be referred to by their volume numbers. The two disks 
provided with this package, volumes 90 and 91, are the update disks. 

BE SURE AND USE ONLY BACK UP COPIES OF BOTH THE SYSTEM DISKS AND 
THE UPDATE DISKS FOR THE UPDATE PROCEDURE. 

Once these four disks have been made ready (using the DOS COPYA program and INIT 
command), the remainder of the process may be performed from the ORCA Monitor. 
Begin by using the unlock command with the = wildcard to unlock all the files on 
volumes 100, 101, and 102. 

Creating Volume 103, MACLIB SOURCE 

Using the Monitor COPY command, begin by copying all of the MACLIB files from 
volume 101 onto volume 104. Use a wildcard specification such as MACLIB= to copy 
them all at once. 

Now copy all of the MACLIB files from the update disk volume 90 onto volume 104, 
again using wildcards. Several of these files will already exist on volume 104; these 
should be copied over. (Hit Y RETURN in response to the “FILE EXISTS. REPLACE?” 
prompt.) 

Once this has been done, volume 104, MACLIB SOURCE, has been updated. 

Now all of the MACLIB files on volume 101 should be deleted, using the wildcard 
specification MACLIB=. 
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Creating Volume 102, SUBLIB SOURCE 

Volume 102, SUBLIB SOURCE version 3.5 is created by simply copying ail of the files 
with the specification SUBS= from the update disk volume 90 onto volume 102. These 
are all replacements of existing files, so they will have to be copied over by hitting Y 
RETURN In response to the “FILE EXISTS. REPLACE?” prompt. 

Also copy the program CONVERT from volume 90 to 102. 

Creating Volume 101, SYSTEM SOURCE 

Having deleted the old MACLIB files from volume 102, it can now be configured as the 

3.5 SYSTEM SOURCE disk. 

Using the wildcard file specification F=, copy all of the operating system source files 
from volume 90 onto volume 101. Again, several of these files will already exist on 
volume 101; these should be copied over by pressing Y RETURN in response to the 
“FILE EXISTS. REPLACE?” prompt. 

Now the new O/S EXTENSION source files should be copied onto volume 102 from the 
update disk volume 91. Use a wildcard filename of OS=. Since none of these files 
existed on volume 101, they will all copy over automatically. 

Volume 101, SYSTEM SOURCE, is now complete and has been updated to CRCA 3.5. 
Creating Volume 100, The SYSTEM Disk 

Finally, the system disk is created by copying all of the old system files— ORCA HELLO, 
APPLESOFT, LOADER, ORCA O/S, ASSEMBLER, MONITOR and LINK EDITOR— 

from the update disk volume 90 onto volume 100. All of these already exist, so they 
should be replaced with the new files using the COPY command. 

In addition, there are two new files that also should be copied over— RAMINIT, which 
initializes RAM cards which are being used as disk emulators; and O/S EXTENSION, 
which is the operating system extension. 

Finally, the SUBLIB.SYSTEM must first be deleted and then re-assembled. To re¬ 
assemble, begin by loading SUBS.COMMON from volume 102. Now assemble It (but do 
not assemble and link). This will create two files, SUBLIB.SYSTEM.ROOT, which 
should be deleted, and SUBLIB.SYSTEM.A, which should be renamed SUBLIB.SYSTEM. 

To complete the installation of the3.5 update, the COMPRESS A,C command should be 
used with volumes 101,102, and 103. Volume 100, thesystem disk, may be placed in the 
following standard order using the SWITCH command: 
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ORCA HELLO 

APPLESOFT 

LOADER 

ORCA 0/S 

0/S EXTENSION 

MONITOR 

RAMINIT 

ASSEMBLER 

LINK EDITOR 

SUBLIB.SYSTEM 

These copies should now be considered the 3.5 masters, and back-ups of these disks 
should be used to re-configure the system for a specific set of hardware by re¬ 
assembling the operating system. 
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Supported Hardware 


The source code for the ORCA/M operating system as supplied on disk two (volume 
101, SYSTEM SOURCE ), is provided to allow maximum flexibility in adapting the 
system to various hardware configurations. Generating a new version of the operating 
system by re-assembling it allows both configuration for a given collection of standard 
hardware and the inclusion of special drivers for non-standard equipment such as 
eighty column boards and hard disks. As Is described in the reference manual, when 
the operating system is re-assembled, a number of prompts are displayed on the 
screen. (These occur when the assembler encounters an AINPT directive.) By entering 
the appropriate responses, the user may select from a number of standard options 
those best suited to a given set of hardware. Using conditional assembly to select the 
corresponding driver routines, the desired version of the operating system is created. 

When modifying the operating system by re-assembly, always use back-up copies. Do 
not modify the original disks in any way. When making back-up copies, remember that 
specific volume numbers are assigned to each of thethree system disks, and these must 
be maintained. If the DOS COPYA program is used, it will automatically copy the 
correct volume number. 

The following messages describing the currently available options will be displayed 
during assembly. The selection of certain options will preclude the selection of others; 
thus not all options are displayed for a given assembly. 

Enter a Y for yes or a^ for no In response to all questions which presume a yes/no reply. 
Otherwise, enter the string specified In the description. 

Do you have an Apple / /e? 

Answering Y (yes) selects certain options such as upper and lower case display 
and input. 
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Does it have 80 columns? 


This prompt will only be displayed if//e was selected above. Ayes answer should 
be given only If the Apple eighty column text card is installed; otherwise, answer 
no, even if an Apple II Plus-type eighty column board is being used. 

Does it have the 64K extension? 

If the //e extended memory card is Installed, answering Y to this prompt causes it 
to be configured as a RAM disk. The logical slot and drive for the emulated drive 
must be selected below in the disk drive configuration section. 

Do you have a Franklin ACE 1000? 

Answering yes selects the Franklin keyboard table in the Monitor. 

Do you have the shift key modification? 

If the shift key modification has been made (wiring the shift key switch to the 
game I/O port), answer Y. 

Can your system display lower-case? 

Answer Y If either a //e or Franklin, an eighty column card, or an Apple with a 
lower-case adapter Is being used and lower-case display is desired. 

Do you have a Videx 80-column card? 

Yes or No. 

Do you have a clock card? 

Enter Y to configure for one of the following clock cards: the California Computer 
Systems clock-calendar card, the Prometheus Versacard, theThunderclock Plus, 
or the Mountain Hardware CPS Multifunction Card. If Y Is entered, the following 
prompts will appear. 

Is it a CCS clock card? 

Yes or No; this configures for the board’s clock function. ' 


Is it a Prometheus Versacard? 


Yes or No; this configures for the board’s clock function. 
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Is it a Thunderclock? 

Yes or No; this configures for the board’s clock function. If yes is selected, the year is 
requested as well. 

Is it a CPS clock card? 

Yes or No; this configures for the board’s clock function. 

What slot is it in? 

This prompt Is displayed If one of the four clock cards above was selected. For 
multi-function cards such as the CPS or Versacard, be sure and give the physical 
slot number of the card, not the slot number the clock may be “phantomed” to. 

Bypass date input? 

If a clock card was not selected, this prompt is displayed, giving the option of 
disabling the date stamping of files within the system. Consequently, the date 
input routine on startup Is bypassed. 

Do you have a drive at slot n, drive n? 

For each ofthegiven slots n, enterY orN if a drive Is installed at that slot and drive 
location. If disk emulation is selected, answer Y for the slot and drive to be 
emulated as well. 

For each yes answer, the following series of prompts is displayed: 

Is it a standard disk? 

If it Is a standard Disk II or compatible35-track drive, enter Y.This exitstothe next 
slot/drive prompt. 

Is it a Legend Disk Emulator? 

If the drive selected is to be used as the disk emulator sipt, answer Y. This causes 
additional prompts to specify the size of the RAM card and the physical slot it is 
found in—which may be different than the logical slot used by the emulator 
routine. The program RAMINIT must be on the boot disk if a disk emulator Is used. 

Is it a IIe RAM disk? 

Answer Y If this is the slot and drive combination that is to be used to access the 
He extended memory card RAM disk. 
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Is it a micro-sci 70 track disk? 

Answer Y or N. Since this is the final choice, selecting N generates an error 
message. 

What is your boot slot (4-7)? 

Enter the slot In which the ORCA/M boot disk will normally be found. 

The boot disk is the disk that the operating system is loaded from. It may also be 
searched for system files If they are not found on the system disk. 

What is your boot drive (4-7)? 

Enter the drive in which the ORCA/M boot disk will normally be found. 

What is your system slot (4-7)? 

Enter the slot in which the ORCA/M system disk will normally be found. The 
system disk is where ORCA normally looks for system files, such as the Monitor. 
The system drive is always searched first, then the boot drive. This allows an 
emulated disk to be used as the system disk. The operating system is first booted 
off of the boot disk, and then the system files (ASSEMBLER, MONITOR and LINK 
EDITOR) are copied onto the emulated disk. 

What is your system drive (4-7)? 

Enter the drive in which the ORCA/M system disk will normally be found. 

What slot is your printer in? 

Enter the number of the slot the printer interface card is in. The conventional slot 
is 1. 

Should the 0/S provide screen echo? 

“Screen Echo” refers to the echoing of characters printed on a printer on the video 
display. Some Interface cards automatically cause the characters printed to be 
echoed; others don’t; others make it an option. 

If the printer card does not cause echoing, or if an eighty column board is being 
used, enter Y, and the operating system will cause each character printed to be 
sent to the screen. 
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Because of the way certain interface cards use page zero memory, it may not 
always be possible to enable screen echoing in any way without a conflict that 
causes undesirable side effects. In these cases, turn screen echo off by entering 

N. 

Printer initialization: 


If a printer initialization string (i. e.: CTRL-I80N) is needed or desired to select the 
correct printer mode, enter the string here. This will be output every time the 
printer is enabled by the PRINT command or PRNT on directive. 

To enter control characters, type the up arrow (A) followed by the upper case letter 
corresponding to the control character; for example: AI80N. 

If any of the following options have been selected, the file O/S EXTENSION must be on 
the boot disk in addition to the file ORCA O/S. Other users may delete it from the system 
disk. Normally, this file will not need to be re-assembled, although the source code Is 
provided. 

//e 

Thunderclock Plus 

Any non-standard disk drive or emulator 
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This program is dedicated to my Father 






This program was started in June of 1980 as a summer project. It sort of grew a little in 
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the most complete assembler language development system ever written for a micro 
computer. I hope that your experiences with it justify that feeling. 
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would like to thank CD Osborne, Bruce Benson, Sandy Croushore, Dave Umphress and 
Rex Fahrquar for proofreading the original User’s Manual and making many 
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was of special help, as he patiently beat the concepts of structured programming into 
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to tell a physicist. I would also like to mention my closest friend. Peg Smith. She didn’t 
do anything (specific) to help the assembler along, but she has always wanted to be 
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Chapter One 
System Overview 

Introduction 


ORCA/M (Object Relocatable Code Assembler for Micros) is a system for writing 
assembly language programs. It brings together a collection of features which, in their 
completeness, makes It unique among microcomputer assembly language 
development systems. 

ORCA was designed to be the single most powerful tool available for the coding of 
sophisticated, high-quality software. For example, it not only includes floating-point 
and double-precision floating-point subroutines and macros, but also supports them 
fully with floating-point “define constant” assembler directives. Perhaps for the first 
time, the availability of this kind of tool allows assembly language to be considered as a 
serious option In the development of complex applications software in addition to 
serving in its usual role as a systems programming language. Thanks to the macro 
language, a high-level interface to the floating-point and other library subroutines is 
provided. 

The assembly language itself was modeled after the macro assembler found on the 
IBM/370 main frame. In addition to this powerful assembler, the system consists of a 
link editor, command monitor and co-resident text editor, and a DOS 3.3 compatible 
operating system. 

The link editor relocates the object modules created by the assembler and resolves 
external references by linking In routines from the system library, creating an 
executable binary file. 

The text editor is screen-oriented, and comparable in features to editors found in 
sophisticated word-processing systems. 
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The operating system moves the assembler, monitor and link editor in and out of 
memory, allowing the different parts of the system to be overlayed. The loading of 
system files is completely transparent, however, and file loading is faster than under 
DOS 3.3. ORCA/M is a disk-oriented system. Disk access has been enhanced by 
eliminating a large percentage of the overhead associated with operation under DOS. 
At the same time, it is completely file-structure compatible with DOS. 

The operating system also contains all printer Interface routines, a date Input routine, 
and code to Interface to a VIdex eighty-column board. Source listings of the operating 
system are provided both in the manual and on disk, allowing the user complete 
freedom to interface with any printer, clock/calendar card, or eighty-column board. 

The assembler supports the standard 6502 instruction set, with the manufacturer’s 
recommended operation codes for the instructions. Additionally, fifty-one assembler 
directives are provided. Including conditional assembly directives and a macro 
language. 

When the system is initialized, the user Is placed in the hands of a command monitor, 
described in detail In the next chapter. The monitor supports many of the familiar Apple 
DOS commands, as well as several welcome extensions, such as a RESTORE 
command, which restores deleted files. In all, there are thirty-nine monitor commands. 

A powerful, co-resident, full screen text editor is available from the monitor. Once 
mastered, its fifty-one editing commands provide a flexible and efficient means with 
which to prepare source files. If the standard forty-column Apple display is used, the 
editor allows up to 80 columns of text to be edited by using horizontal scrolling; 
additionally, drivers for eighty-column boards may be linked in to the operating system. 
A driver for the Videx eighty-column board is included with the operating system 
source; instructions for writing drivers for other boards are given. The entire set of 
printable ASCII characters may be entered using the editor, including upper and lower 
case letters. If a lower-case adapter Is available, the system may be configured to 
display lower case; otherwise, uppercase only may be used, or uppercase as inverse 
video and lowercase as uppercase. The shift key modification Is also a configuration 
option. 

The macro assembler itself is run by issuing one of several “assemble” commands from 
the monitor. Assembler options may either be entered on the Input line along with the 
assemble command, or included in the source file as desired. The assembler then 
assembles the source file in memory, chains in any additional source files as needed, 
and returns control to the operating system. If a “keep” file has been specified, 
relocatable object code Is stored directly to disk. From there, control is automatically 
passed on to the monitor or link editor, depending on the type of assemble command 
used. There are single monitor commands that Initiate assembly; assembly and link 
editing; and assembly, link editing, and execution of the assembled program. Since the 
source file in memory may direct the assembler to use additional source files from disk, 
programs of any size may be assembled. 
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“Any size” means exactly that - the ORCA/M system itself consists of over 38,000 fully 
commented lines of code, spanning seven disks. 

The final component of the system, mentioned briefly above, is the relocating link 
editor. It is entered in two ways: using the monitor LINK command, or via an automatic 
call fromJLhe operating system after an assembly Is finished if one of the “assemble and 
link” commands was given. 

Users who are unfamiliar with program development using relocatable code and a link 
editor may basically Ignore the link edit process until they become more familiar with 
the system. For example, the RUN command will assemble the file in memory, 
automatically link edit the result, and execute the completed program, all without 
additional user Intervention. Once the capabilities of the link editor are studied. It will be 
discovered that they greatly extend the power and flexibility of the system. It allows a 
program to be moved to any memory location without re-assembly. It also makes It 
possible to re-assemble a few subroutines within a large program, and re-link them to 
the previously assembled object code of the same main program, rather than requiring 
re-assembly of the entire program. Finally, its most powerful function is to link in library 
subroutines without including the source code In the main program, or even re¬ 
assembling them. 

More experienced users will find that chapter five, which describes the link editor, gives 
them a quick Insight into some of the advanced capabilities of the system. 

One of the most frustrating things for a beginner at assembly language programming is 
the lack of some very basic Instructions and subroutines. With conventional 
assemblers, weeks can be spent In building up a library of subroutines to do such 
rudimentary tasks as printing a line or multiplying two-byte integers. With ORCA/M this 
problem does not exist, as a complete set of general-purpose macros and subroutines is 
provided. Subroutines for printing a string of characters on the screen, beeping the 
speaker, getting a line of input, or performing math operations, are all available, each 
called by coding a single macro. The library also include high and low resolution 
graphics, logic and looping functions, two byte integer math, four byte Integer math, 
and single and double precision floating point math, including transcendental 
functions. Source code for both the macros and subroutines is also Included In the 
manual and on disk. 


Using This Manual 

This manual is written to teach the programmer how the ORCA/M development system 
is used to write assembly language programs, and to provide a reference for the 
assembler and the 6502 microprocessor. It does not teach assembly language 
programming. An experienced assembly language programmer who has never used 
the 6502 should find this manual sufficient, but the novice will need to add a book 
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directed at teaching assembly language itself. There are several recommeded books in 
the bibliography. 

Despite the power and sophistication of the program, the user’s manual for ORCA/M is 
designed to allow the programmer with moderate assembly language experience to 
make the transition to ORCA quickly and easily, without requiring that its advanced 
features be learned before the system is used. 

There is probably too much information in this manual to digest In one reading. 
Nevertheless, the best way to learn about the system is to start using it. Therefore, when 
more advanced features such as the macro language are described, the text will note 
such material as advanced. This can be skipped or skimmed through when reading the 
manual for the first time. Mastery of the simpler essentials of the system will provide as 
many capabilities as most other assemblers. After using the program for a while, the 
remaining information will make more sense and be easier to remember. 

The manual is organized into three main parts: part one. The System, Is the basic 
reference to using the assembler. It presents In four chapters the monitor, editor, 
assembler, and link editor. The section on the assembler Itself is further divided into 
four parts: one on using the assembler and assembler command parameters; how to 
code source statements; assembler directives; and finally, the macro language and 
conditional assembly. 

Part two. Using the System includes details on using all of the macros provided with the 
system. It also contains a chapter called The Style Manual, which discusses practical 
considerations in making effective use of the assembler and the macro facility. 

Part three consists of several appendices detailing various aspects of the system, as 
well as the source listings for the operating system, macro libraries, and subroutine 
libraries. 

It is assumed that the user has a copy of the Apple II reference manual available. The 
information It provides on the internal organization and capabilities of the machine is 
invaluable for assembly language programming. 

As seen in the outline given above, ORCA/M is not merely an assembler, but a carefully 
designed environment which provides the programmer with many new and powerful 
features. Aside from learning the specifics of the assembler directives and the macro 
language, the basics such as how to edit, save, and re-load a file must be learned. 

Begin by studying the next two chapters. The Monitor and The Editor, and 
experimenting with the different editor and monitor commands for a while. Once these 
become familiar, move on to the study of the assembler itself. 

Finally, the single most valuable tool for both learning about and using the assembler is 
the reference card. Use it. 
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Programming with ORCA 

Users familiar with other assemblers available for the Apple will find that, in addition to 
having to learn the macro language, a few changes will be neccessary in the way they 
code a program. This is because the assembler Is designed to help enforce structured 
programming by encouraging the development of multiple code segments within a 
single source file. The division into code segments also makes the assembler more 
efficient. A very powerful benefit that results is that these segements may be 
individually re-assembled as needed during the development process, and re-linked to 
a previously assembled object module. This results in a dramatic increase in 
productivity, as the time-consuming re-assembly of entire programs to effect small 
changes is no longer neccessary. 

The concept of the code segment, or, as it is loosely called In this manual, the 
subroutine, is probably the most important new concept that must be understood 
before being able to use the system effectively. The code segment is referred to as a 
subroutine because it Is intended to correspond generally to the subroutine as defined 
by the 6502 JSR (jump to subroutine) and RTS (return from subroutine) machine 
language instructions. As will be discovered, however, this correspondence will not and 
need not always be a literal one. 

The first Important characteristic of the subroutine Is that all labels defined within it, 
except via explicit global declarations, are limited In scope to the subroutine Itself. This 
means that if a label such as LOOP1 Is defined as the destination of a branch instruction 
within one subroutine, that label will be undefined for all other subroutines (unless 
redefined by the other subroutines). This is generally a convenience in that the same 
label (such as LOOP1 ) may be re-used In different subroutine without resorting to great 
efforts of Imagination to define unique but meaningful labels. 

A coding constraint imposed by the nature of the subroutine helps to Illustrate Its 
structure: a relative branch may not betaken to a (globally defined) location outsidethe 
range of the subroutine. This Is because the subroutine is fundamentally a separately 
assembled unit whose execution location will be determined only subsequently, by the 
link editor; the relative positions of locations within other subroutines is subject to 
change. 

It is possible to code an application as one large subroutine, and some programmers 
may find their initlaltendency istodothat. It will soon be found, however, thatthe useof 
several code segments within a program brings a structure and orderliness to the 
program that make it much easier to develop and debug. 

By coding each subroutine as a different code segment, the assembler can not only 
selectively re-assemble a given subroutine or list of subroutines within a large source 
file (or stream of source files), but the link editor can link these individual subroutine 
assemblies to previous assemblies. These may consist of either the rest of the object 
modules for the same program, or library routines, such as those provided with the 
system. 
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System Configuration 

Introduction 

As distributed, ORCA is set up for use with a minimally-configured Apple II computer; 
forty column, upper-case only display with a single disk drive in slot six, drive one. 
There are a number of configuration options which allow ORCA to take advantage of 
additional hardware available on a specific system. 

ORCA is re-configurerl by re-assembling the operating system itself, the source for 
which is provided on the disk labeled SYSTEM SOURCE. During pass one of the 
assembly, prompts are displayed (using the AINPT directive described on page90). By 
entering the appropriate responses, conditional assembly directives within the 
operating sytem source code cause the desired version of the operating system to be 
generated. 

For users with more than one disk drive, re-assembling the system to reflect the drive 
configuration is one of the most important options. 

From the monitor command level, files In any available drives may be accessed using 
slot and drive designations. The assembler and linker, however, select files by volume 
number, not by physical device. When searching for a given volume, the assembler may 
access any and all drives that are on-line. To prevent the system from hanging by 
searching for a drive in an inactive slot, the location of the available drives must 
explicitly be made known to the operating system at configuration time. 

Since the system as distributed Is configured for a one-drive system, this would suggest 
that only one drive may be used for re-assembly of the operating system itself. This Is 
not the case; by typing the command USER from the monitor, the operating system is 
temporarily modified to recognize a second drive. If ORCA is re-booted. It will again 
only recognize the drive in slot six, drive one. When the system is permanently 
reconfigured by re-assembly, the USER command assembles to an RTS instruction; it is 
Intended for the implemention of a user defined command. However, on the master 
copy of the system as distributed, the USER command functions to enable drive two. 

Re-assembling the operating system 

Before attempting to re-assemblethe operating system. It would be wise have first read 
the manual and to experiment with the editor and monitor commands In the minimal 
configuration. 

Re-assembly of the operating system Is like any other assembly. Users with two drive 
systems should type USER before starting, to enable two-drive assembly; otherwise, 
begin by loading the first file In the operating sytem from the SYSTEM SOURCE disk 
provided by typing 
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LOAD FOPRS 

from the monitor (the # prompt). Users with two drives should havethe SYSTEM disk in 
drive one and the SYSTEM SOURCE disk in drive two and add , D2 to the LOAD 
command. Users with single drive systems will have to swap disks during assembly; the 
assembler keeps track of what disks are needed by volume number. 

Be sure that when the operating system is re-assembled, back-up copies of the 
ORCAIM system disks are used. These may be made using the COPYA utility provided 
with the DOS 3.3 system master disk. 

Once FOPRS has been loaded, simply type ASML. The assembler will be loaded (if the 
system disk is not on-line, the assembler will prompt for It to be put In the drive). When 
the first AINPT directive is encountered, the assembler will pause and prompt the 
operator to select the first of the configuration options. Enter the appropriate response 
and hit RETURN. The assembler continues to prompt for configuration options until 
they have all been entered. 

Since the available options are subject to change as new drivers are added to the 
system, the source file OPTIONS on the SYSTEM SOURCE disk contains adescriptlon 
of those options currently available. 

During the assembly process, object code is being stored to the system disk. If a one- 
drive system is being used, the SYSTEM disk will have to be exchanged with the 
SYSTEM SOURCE disk every time object code Is written or a new source file Is 
appended Into memory. These will be requested by volume number; the SYSTEM disk is 
volume 100, and the SYSTEM SOURCE disk is volume 101. 

The assembly process will take a few minutes to complete. When it Is finished, catalog 
the system disk by typing C D1 with the system disk in drive one. In addition to the file 
ORCA O/S, which was there before the assembly, there will be two addtional files: 
ORCA O/S.ROOT and ORCA O/S.A. These are the intermediate object modules, which 
are no longer neccessary. Delete them by typing 

DELETE ORCA O/S . = 

Be sure to Include the dot (period) between the S and the = sign; otherwise, the 
operating system just created will also be deleted. Since a wildcard is being used in a file 
name, the system asks: 


Do you want prompting? 

Type N and all of the Intermediate files will be deleted. 

To clean up the appearance of the catalog a bit, use the monitor command COMPRESS C 
followed by LOCK = (Again answer N to the DO YOU WANT PROMPTING? message.) 
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The operating system is now configured for the options specified. 

To re-initializethe system (the old copy of the operating system is still In memory), type 
DOS to re-boot the disk. The ORCA operating system is now configured to recognize 
the hardware options selected. 


Files on the ORCA/M disks 


The ORCA/M system is distributed on three disks, labeled the SYSTEM disk, the 
SYSTEM SOURCE disk, and the SUBLIB SOURCE disk. 

Files on the SYSTEM disk: 

The system disk has all of the files neccesary to operate the assembler. The operating 
system expects to have it on-line; otherwise, it will prompt for It to be inserted into the 
system drive. 

ORCA HELLO 

This Is the “greeting” program that Is run every time the disk Is booted. It is a short 
Applesoft BASIC program which loads the files LOADER and ORCA O/S into memory. 
It must be present to boot the system. 

LOADER 

This is a short assembly language program which initializes a 16k RAM card If one is 
present, and moves the operating system to Its execution address. Relocating the 
operating system In this way is necessary because it occupies the same area in memory 
as Apple DOS, which must be used to do the Initial loading. This program is required on 
the boot disk. 

ORCA O/S 

As the name Implies, this file Is the operating system forthe assembler. It contains all of 
the subroutines which interface with eighty-column boards, clock calendar cards and 
printers. It loads the other parts of the system into core as needed. The source code for 
the operating system Is on the SYSTEM SOURCE disk. This program is required on the 
boot disk. 

MONITOR 

The monitor and text editor are contained in this file. It Is loaded by the operating 
system on initialization, and reloaded at the end of each assembly or link edit. This 
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program is required on the system disk andthe bootdisk (which will bethesame unless 
specifically configured otherwise). 

ASSEMBLER 

This Is the macro assembler that is the heart of the system. It Is loaded by the operating 
system as needed. This program is required on the system disk. 

LINK EDITOR 

The link editor is loaded by the operating system afterthe assembler has finished with a 
program. It connects all of the subroutines assembled, searching the subroutine 
libraries for unresolved references. It is required on the system disk. 

SUBLIB.SYSTEM 

This Is an object module, with file type R. It contains the pre-assembled subroutine 
library. The link editor will search this file automatically for unresolved references in a 
program if this file is on the system disk at link edit time. See the chapter describing the 
link editor for restrictions when using more than one library. 


Files on the SYSTEM SOURCE disk: 

The SYSTEM SOURCE disk contaings the source for the operating system; this disk Is 
used to re-configure ORCA/M by re-assembling the operating system. The macro 
libraries are also on this disk. 

FOPRS.= 

Files beginning with FOPRS are the source code for the operating system. (The 
wildcard symbol (=) Indicates any filename that begins with this prefix). The operating 
system is listed on page 219. 

FLOAD 

Source code for the loader program. 

MACLIB.= 

There are several files whose names begin with MACLIB. These are the macro libraries 
described in chapter six and listed on page 251. 

Files on the SUBLIB.SOURCE disk: 

This disk contains all of the source files neccessary to generate the SUBLIB.SYSTEM 
object module. 
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CONVERT 

This is a file conversion utility, used to convert source files to standard DOS text files 
and vice versa. See appendix F for a description. 

FIX COUNT 

This program sets-the sector count used by the catalog routine to its correct two byte 
value. It may be required for files created by programs which did not use both bytes. See 
appendix F for a description. 

SUBS.COMMON 

This is the data area for the subroutine libraries. It contains the global equates that 
define all zero page locations used by the library subroutines, as well as the random 
number generator used by the system. 

SUBS.DPMATH = 

The six files that start with these characters contain the double precision math 
subroutines. 

SUBS.FPMATH= 

These five files contain the single precision floating point library subroutines. 

SUBS.INT4MATH= 

The four byte integer subroutines are contained In these two files. 

SUBS.MACRO 

This file contains the macros used inthesubroutinelibraries.They are alltaken directly 
from the macro files found on the SYSTEM SOURCE disk. They are condensed Into one 
file to speed up the assembly process. 

SUBS.UTILITY= 

The last two files contain the two byte Integer subroutines, the character output 
subroutine used by the PRINT and WRITE macros, and a few general purpose 
subroutines used by other subroutines in the library. 
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chapter Two 
The Monitor 

Introduction 


To a lot of people, a monitor is the Apple II program with an asterisk for a prompt 
character that turns up whenever a program bombs. The term “monitor” is much 
broader in scope than this; it can mean any program which provides an interactive 
command language. The ORCA/M monitor provides a set of commands that allows files 
on disk to be examined and changed, assembler source files to be loaded and saved, 
and the assembler, link editor and text editor programs included with the system to be 
executed. 

The monitor is the program entered when the system is first booted. Placing the disk in 
slot six, drive one, and powering up the system or typing PR#6 from BASIC runs the 
program ORCA HELLO, which simply asks 

ENTER ORCA MONITOR? 

By keying Y, the operating system is loaded and prompts for the current date to be 
entered. The date is entered as a numeric day, month name, and year. Only the first 
three letters of the month are required; anything after that is ignored. The year can be 
two or four digits. For example, all of the following are valid dates (and are the same): 

16 JUN 82 
16 JUNIPER 1982 
16 JUNE 82 

After the date has been entered, the operating system loads the monitor and gives the 
monitor prompt, followed by a flashing cursor. 
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In all, there are thiry-nine monitor commands. Most of them should seem familar, 
looking a lot like Apple DOS or some of the disk utility packages. Since these 
commands are already familiar to most Apple II users, it should be possible to learn 
them in a single sitting. To learn just enough to get by, however, start with the essential 
commands listed below: 


APPEND XXX 
ASML 

BRUN XXX 
CATALOG XXX 
DELETE XXX 
DOS 
EDIT 

LOAD XXX 
NEW 

SAVE XXX 


Append file xxx to the file in memory. 

Assemble and link edit. 

Execute the binary file xxx. 

Catalog a disk. 

Delete file xxx from the disk. 

Reboot Apple DOS. 

Edit the file in memory. 

Load file xxx into memory. 

Erase the file in memory and enter the text editor. 
Save the file In memory onto disk, using 
file name xxx. 


The detailed command descriptions given later in this chapter are in alphabetical order 
for easy reference. Since this is not going to be the best orderto learn them in, the most 
important commands are introduced In logical groupings. 

To begin with, there are several commands which function just as they do with DOS 3.3. 
These are BRUN (execute a binary program), DELETE (delete a file from disk), LOCK 
(lock a file), UNLOCK (unlock a file), and RENAME (rename a file). Slot, drive and 
volume parameters may be used exactly as they are with DOS. 

TheORCA CATALOG command is very similarto DOS, but it has a few added features. 
One is that the command may be aborted by typing ESC. A more powerful difference is 
using CATALOG with a file name parameter. Only the file named is cataloged. When 
combined with wildcard file names, (described later in this section), this results In a 
convenient way to catalog just a few of the files on the disk. The monitor’s CATALOG 
command also reports the percentage of space on disk already in use. 

Although these commands can work the same way as under DOS, they do not need to 
be entered in exactly the same way. Take the CATALOG command as an example: 
when using DOS to catalog a disk, the command CATALOG is typed, followed by 
RETURN. This still works. Additionally, the command name may be abbreviated. For 
example, C, CA, CAT, CATA, CATAL, and CATALO all cause the disk to be cataloged. 
CATS however, will not work; It gives an Invalid Command error. The convenience of 
using this shorthand has a price: all command names must end with a space (or 
RETURN). DOS will catalog the disk in drive two with either CATALOG D2 or 
CATALOG,D2. Only the first command works with the ORCA monitor. Of course, 
C D2, or C ,D2 may be used - just be sure there Is a space after the command. 

At this point, it is fair to wonder how the monitor can distinguish CATALOG from other 
commands starting with C, like COMPRESS, if only thefirst letter is used. The answer is 
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that it can’t. To get COMPRESS, at least the first two letters, CO, must be typed. Since 
COMPRESS Is the first command that starts with CO, it Is executed. To get COPY, the 
first three letters are needed. In other words, commands are checked in alphabetical 
order. The first command that matches all letters typed Is used. Thus CATALOG is 
selected if C is typed, since CATALOG is the first command in alphabetical order of the 
seven commands starting with a C. 

As with all rules, there Is an exception. The L commands are not In strict alphabetical 
order; LOAD comes before LINK. This is because LOAD is one of the most commonly 
used commands on the entire system, and LINK is used only rarely. To execute the 
LOAD command, only L need be typed. If alphabetical order had been used, LO would 
have been required. 

The final difference in the way commands are used Is In the way they use file names. The 
use of CATALOG as an example will be confined, since it will accept a file name 
parameter. The difference Is that a wildcard character is allowed. Entering 

C M= 

will catalog all of the files that have M as a first character. 

C =.= 

gives all files that have a period somewhere In the file name. Finally, 

C = 

works like a normal catalog command; all files are listed. If the wildcard parameter is 
used with a command like LOAD, which only loads one file, the first file that fits the file 
name mask Is selected. Most commands (CATALOG is not one of them) allow optional 
prompting with each file that matchesthewildcardspeclflcation.TakeDELETE= as an 
example. The monitor responds to this command by displaying the message 

Do you want prompting? 

Y and N are the two permissable responses. N causes all files on the disk to be deleted; 
their file names are listed as they are deleted. Typing Y causes the system to pause for 
confirmation before the command Is executed for each file. Respond to this by keying Y 
or N for each file; Y deletes the file displayed, N skips the function and goes on to the 
next file. (The ORCA/M wildcard parameter functions Identically to the DOS FID 
program.) 

There are two commands which have different meanings from their DOS counterparts: 
LOAD and SAVE. With DOS, these commands load a BASIC program from disk or save 
one to disk. The ORCA/M monitor uses them for a similar purpose to load and save 
source files. (A source file contains the source code for a program; it Is entered using 
the text editor.) As with BASIC, only one file can be in memory at a time. Loading 
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another file replaces the file In memory. Finally, note that if SAVE is entered without a 
file name, the monitor lists the name of the last file loaded or saved, and asks if It should 
be used as the output file name; this saves having to retype the file name when editing. 

Source files are created using the text editor. Although it Is described In its own chapter 
as a separate program, the editor and monitor are co-resident; that is, they are 
contained In the same file. The two monitor commands which transfer control to the 
editor are EDIT and NEW. When the text editor is entered using EDIT, the file that was 
In memory is preserved, and can be re-edited. Using NEW erases any file in memory and 
begins editing with a clear text buffer. 

The last major category of commands is the group used to assemble and link edit a 
program. There arefourfunctions, butthereareelghtcommand names. This issothat if 
compilers are added to the system later, it will not be necessary to ASSEMBLE a Pascal 
program; COMPILE can be used Instead. As far as the system is concerned, they both 
mean the same thing, that is, load the currently active language and start processing the 
file in memory. 

ASSEMBLE (or COMPILE) does not call the link editor, so this command does not 
result in an executable program. Instead, it produces relocatable object modules, 
which are the files used as input to the link editor. When a program Is assembled, it 
needs to be linked before it can be executed. Linking is done using the LINK command, 
which, like the “assemble” commands, has a number of parameters. These parameters 
are covered in detail in the chapters which describe the assembler and link editor. 

Although assembling and linking the program separately provides a great deal of 
flexibility. It is unnecessarily complicated. The two steps can be combined intoasingle 
step using the ASML command (assemble and link). This assembles the file in memory 
and automatically link edits the result. No parameters are required, although there are 
several that may be used. CMPL (compile and link) does the same thing. 

Finally, there is a single command that does It all. After assembling the file in memory 
and linking the result to produce a final program, the program is executed by the RUN 
command. RUN actually has two other names: ASMLG (assemble, link and go) or 
CMPLG (compile, link and go). 

Finally, the command DOS is used to re-boot the disk (like typing PR#6). To boot a disk 
in a slot other than six, enter the slot number after the DOS command. 


Monitor Command Reference 


Entering Monitor Commands 

Monitor commands may be entered any time the # prompt and a cursor is displayed. 
Each command description given below starts with a command format, showing how 
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the command should be entered. It is only neccesary tototypeenough of the command 
to distinguish it from other commands which precede it alphabetically. For example, C 
Is sufficient to get a catalog of the disk. To check the disk, CH is all that would be 
required. If more letters than required are entered, they are checked against the 
complete command to insurethat all of the letters are valid. For example, CHE works for 
CHECK, but CHK would result in an Invalid Command error. If a command requires 
operands, at least one space must follow the command. This distinguishes a command 
from Its operands. 

Commands are searched in alphabetical order, except for LOAD. LOAD Is the first 
command In the list of commands beginning with L, since It Is used more often than 
LINK. Thus L will load a file, whereas LO would be needed If alphabetical order was 
adhered to In this case. Page 197 lists all of the monitor commands in the order that they 
appear in the command table. 

Most commands that use disk file names can use the wildcard character =. When 
encountered, the = character can substitute for any number of characters (or zero 
characters). For example. 


CATALOG MACLIB = 

produces a catalog of all files beginning with the characters “MACLIB”. If wildcard 
filenames cannot be used with a command, this is noted In its description. 

Commands which reference disk files allow the use of volume, slot and drive 
parameters. These parameters are optional; they are used to switch the disk that the 
monitor is using or to check the volume parameter of a disk. To code them, follow the 
filename used with the command by a comma, the first letter of the parameter (S, D, or 
V), and the value of the parameter. Any combination of parameters in any order may be 
used. For example, thefollowing commands will append afllefrom slotfive, drivetwoto 
a file from slot six, drive one, and save the result on the disk in slot six, drive one. 

LOAD FILE1,S6,D1 
APPEND FILE2,D2,S5 
SAVE FILE1,D1,S6 

Once a disk has been referenced. It remains the default disk until a slot or drive 
parameter is encountered that changes it. Commands which cause access to the 
system drive, such as ASSEMBLE, do not alter the current drive. 

A technical detail worth noting is the fact that when Apple DOS checks the volume 
parameter, it uses the volume number embedded in the sector header, which can only 
be changed using the DOS INIT command. The assembler uses the volume number In 
the volume table of contents (VTOC), which is located at track seventeen, sector zero. If 
the volume number in the VTOC is changed using the VOLUME command explained 
below, this could result In different responses from Apple DOS and the ORCA/M 
operating system. This Is because the VOLUME command only changes the volume 
number found in the VTOC. 
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Commands which cause an assembly or a compile can take a number of parameters. 
These are described beginning on page48 for the assembler, and on page97 forthe link 
editor. 

Monitor Command Descriptions 

APPEND XXX - Append a File 

This command appends file xxx to the file In memory. Prior to loading file xxx, all blank 
lines are removed from the end of thefile In memory. FIlexxx isthen placed at the end of 
the file in memory. If the wildcard parameter Is used, only the first file that fits the* 
wildcard name Is appended. 

ASML - Assemble and Link 

The file in memory is assembled. If the maximum error level found is less than or equal 
to the maximum allowed error, (see MERR on page 75), and if thefile was saved, thefile 
is automatically linked. 

ASMLG - Assemble Link and Go 

The file in memory Is assembled. Following assembly, if thefile was saved on disk and if 
the maximum error level encountered was less than or equal to the maximum allowed 
error (see MERR on page 75), the assembled program Is automatically linked. If the 
maximum error is still less than the allowed maximum, the program is executed. 
Execution of the program will fail if it overwrites the operating system (which is In the 
process of loading the program). The operating system is located from $8000 to $BFFF. 

ASSEMBLE - Assemble the File in Memory 

The assembler is loaded in place of the monitor and directed to assemble the text file 
currently In memory. After the assembly has been completed, the assembler returns 
control to the operating system, which reloads the monitor. See chapter four for a 
description of the assembly process. 

BRUN xxx - Binary Run 

File xxx is executed. This command is equivalent to the DOS command by the same 
name. If the program ends with an RTS, control will pass back to the operating system. 
The operating system will then reload the monitor. 

CATALOG xxx - Catalog the Disk 

The disk volume number and amount of the disk in use are printed. The files on the disk 
are then listed in the order that they are encountered on the disk directory. Each file 
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name is preceded with afiletype identifier and the number of sectors used (indecimal). 
The file type identifier is preceded by an asterisk if the file is locked. File types include 

A - Applesoft BASIC Programs 
B - Binary files and assembled programs 
I - Integer Basic Programs 

R - Relocatable files (for input to the link editor) 

S - Assembler source files 
T - DOS text files 

The file name is optional. When used, it Is generally in conjunction with the wildcard 
parameter. For example, the command 

CATALOG MACLIB. = 

would produce a catalog of only those files which start with the characters “MACLIB.”. 
CMPL - Compile and Link 

This command is identical to ASML; the “compile” analogs of the assemble commands 
are included to allow compilers to be Installed. It would be awkward to invoke a 
compiler using an “assemble” command. 

CMPLG - Compile Link and Go 

This command is identical to ASMLG. 

CHECK - Check a Disk 

The disk is checked for bad sectors. If anyarefound,their track and sector numbers are 
listed. If files are endangered, the file name Is also listed. If the bad sector has not been 
used, it is reserved in the VTOC. 

A sector Is considered bad if the RWTS subroutine encounters an error when It tries to 
load the sector. 

COMPILE - Compile 

This command is identical to ASSEMBLE. (See above). 

COMPRESS - Compress the Disk 

This command can perform two functions, depending on the parameters coded. The 
parameters may be coded in any order among themselves, but must precede slot, drive 
and volume parameters. The parameters are separated by commas. 
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A - Alphabetize Catalog 

Entries in the catalog are placed in alphabetical order. 

C - Compress Catalog 

All catalog entries corresponding to deleted files are moved to the end of the catalog 
chain. This forces the next catalog entry to be placed at the end of the current 
catalog, rather than in the middle as can happen with Apple DOS. Deleted file entries 
are not lost from the chain, so RESTORE can still be used. 

COPY - Copy Files 

Files may be copied from one disk to another with this command. After the command 
has been entered, it prompts for the disk slot and drive numbers of the source and 
destination disks, and the file name to be copied. Wildcards are valid file names. 

If the file being copied is already on the destination disk, a message is displayed asking 
If It is to be replaced. Entering any reply that starts with a Y deletes the old file and 
replaces It with the file being copied. Replies starting with an N invoke a prompt for a 
new file name. The file being copied is then copied using the new file name provided. 
Hitting RETURN without entering a file name cancels the copy. 

DELETE XXX - Delete a File 

File XXX Is deleted from the disk. This command is Identical in function to the DOS 
command of the same name, except that it can use the wildcard parameter. 

DOS X - Boot DOS 

Apple DOS is booted. This Is equivalent to IN#6 or PR#6 from BASIC. If x is coded. It Is 
used as the slot number to boot from. 

EDIT - Soft Entry to the Text Editor 

This command enters the edit mode without disturbing the file in memory. The first 
page of the file in memory is displayed, and the edit cursor is placed in the upper left- 
hand corner. Using this command without first having loaded or entered a program (see 
NEW on page the next page) may result in garbage text being found In the text file. 

Normally, this command is used to edit a file loaded from disk or left in memory while 
other monitor commands are used. It can also be used to attempt recovery of a file left in 
memory after leaving the monitor. So long as the text buffer has not been disturbed, the 
file will be intact. The text buffer is located from $7000 to $8FFF. 
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EXPAND - Expand Load 

After a file is loaded, the date of the last modification, update number and language are 
printed. The update number is the number of times the file has been saved. 

This command represents the default form for a LOAD command, since the above 
information Is normally printed. It Is needed only if NOEXPAND has previously been 
used. 

FREE - Display Memory Used 

This command displays the percentage of the text file used by the file currently In the 
text edit buffer. Since the text edit buffer is immediately followed by a macro buffer of 
the same size, files up to 200% full can be safely accommodated. If a file exceeds 200%, It 
will begin overwriting the operating system, which followsthe macro buffer in memory. 
If this happens, it may not be possible to save the file. 

Although the text editor can accommodate files over 100% full, the assembler cannot. 
All files must be reduced to under 100% before assembly, or the assembler will give a 
terminal error. 

LOAD XXX - Load File xxx 

This command loads file xxx from disk into the text edit buffer. The file must be of type S 
(source code). 

LINK xxx - Link Edit 

A link edit Is performed on file xxx. The link edit process is described fully in chapter 
five, including the parameters that may be used with this command. 

LOCK xxx - Lock File xxx 

File xxx is locked. Any attempt to delete or change it will result in a File Locked error 
message. The file may be unlocked using the UNLOCK command. 

MARGIN X - Set Margin 

When the monitor PRINT command is used, or when the assembler or link editor send 
their outputto a printer, thesystem can printspaces at the start of each line to adjustthe 
left margin. Symbol table sizes are adjusted so that they will still fit on an eighty column 
printer, even with the margin. This command sets the margin used to x columns from 
the left. The default margin Is zero. 
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NEW - Hard Entry to Text Editor 

This command deletes the text edit file In memory and then enters the text edit mode. 
The edit cursor is placed at the upper left corner of the blank first page. This command is 
used to enter the editor when the system Is first brought up orwhenthefile in memory is 
no longer needed. 

NOEXPAND - Don’t Expand Loads 

The date of the last modification, update number and language are no longer printed 
after a LOAD command. 

PEEK - Examine and Change Disk Sectors 

The first catalog sector (track seventeen, sector fifteen) is displayed on the screen In 
hexadecimal format. The data in the disk sector may now be edited, using the single-key 
commands described below. They are entered by typing the key indicated. Control keys 
are entered by holding the CTRL key down while the function key Is pressed. Any key 
other than those listed below is Interpreted as a change to the sector on display. If the 
key is valid for the current input mode, it replaces the contents of the sector at the cursor 
location. If the key is not valid (for example, a G on a hexadecimal display) it is Ignored. 
Changes are made to an Internal buffer, and do not effect the disk contents unless the 
CTRL W command (write) is used. 

ESC - Change Display Screen 

The disk sector can be displayed either In hexadecimal, as it is when the routine Is 
entered, or In character format. (Characters are displayed simply as Apple II screen 
characters). To change from one display mode to the other, use the ESC key. 

CTRL D - Change Display Mode 

Use of this command in the character display mode causes the most significant bit of 
each byte to be inverted. This can be useful when examining standard ASCII files. 
The command is a toggle; using it a second time returns the screen to its original 
form. 

CTRL I - Move Cursor Up 

The cursor is moved up one line. If it started on the top line, it Is placed on the bottom 
line. 

CTRL J - Move Cursor Left 

The cursor is moved left one character. If the cursor started In the left most display 
column, it is placed at the end of the next line up. 
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CTRL K - Move Cursor Right 

The cursor is moved right one character. If the cursor started at the end of a line, it is 
placed at the beginning of the next line down. 

CTRL M - Move Cursor Down 

The cursor is moved down one line. If it started on the bottom line, it is placed on the 
top line. 

CTRL P - Print Page 

The current disk sector is printed. If a printer is not connected when the command Is 
issued, the system will hang. The sector is printed in both hexadecimal and 
alphanumeric form. Before printing alphanumeric characters, the high order bit is 
set. Control characters are converted to blanks before printing. 

CTRLQ - Quit 

Control is returned to the monitor. 

CTRL R - Read a Sector 

This command prompts for a track and sector number. The chosen track and sector 
is then read into memory and displayed. The track and sector numbers can be 
entered In either decimal or hexadecimal. If hexadecimal numbers are desired, prefix 
the number with a $ character. 

CTRL W - Write a Sector 

This command also prompts for a track and sector number. After allowing a chance 
to abort the command, the sector currently being displayed is written to the 
indicated track and sector on disk. 

PRINT - Print File 

The file in memory is printed without assembling, resolving copy and append directives, 
or resolving macro Instructions. Unless the operating system has been configured 
otherwise, the output Is sent to slot one, where an eighty column printer Is expected. 

Each line Is preceded by a four digit line number and three spaces. After each group of 
sixty lines, six blank lines are printed to advance to the next page. 

This command should be used only If a printer Ison line; otherwise the system will hang, 
waiting for a printer response which never arrives. 
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PROFF - Printer Off 

Monitor input and output are not sent to the printer. This is the default mode. 

PRON - Printer On 

Any text entered from the keyboard or written to the screen is sent to the printer. If a 
printer Is not connected and turned on when this command is used, the system will 
hang. Entry Into the text edit mode or use of the PEEK command turns the printer off 
until control Is returned to the monitor. Assemblies, compiles and link edits also turn the 
printer off but do not turn it back on when control is returned to the monitor. 

QUIT - Exits the System 

Control is passed to the Apple monitor. The system may be re-entered using BOOOG, 
typing CTRL Y, or on Autostart ROM models, by hitting RESET. Remember that Apple 
DOS has been overwritten. The disk must be rebooted to use DOS. 

RENAME XXX, yyy - Rename File xxx 

Changes the name of file xxx to yyy. This command is identical in function to the DOS 
command by the same name. Volume, slot and drive parameters may be used. Wildcard 
parameters can only be used in the first (xxx) file name. 

RESET - Reset Update Number 

The byte which holds the number of times a source file has been saved is reset to zero. 
The next time the file is saved, the count will be incremented to one. This can be used 
after major version changes to keep track of which files have been changed. 

RESTORE xxx - Restore File xxx 

The disk is searched for a deleted file with the name xxx. If the file Is found and none of 
Its sectors have been reused, it is restored. The wildcard parameter cannot be used in 
the file name for this command. 

RUN xxx - Assemble, Link and Execute a Program 

This Is equivalent to the ASMLG command. 

SAVE xxx - Save File xxx 

This command saves the file in the text edit buffer on disk, naming the file xxx. Volume, 
slot and drive parameters may be used. The file type will be S (source file). The date and 
current language is saved, along with a number indicating how many times the file has 
been changed (which Is incremented each time the SAVE command is used). This 
number Is called the update number, and is displayed when the file is loaded. The 
update number is modulo 256. 
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If the file has been saved before, the number of sectors needed to store the file can 
change. Unlike Apple DOS, if fewer sectors are needed, the unused sectors are 
released. 

If no file name is given the system asks if the old file name should be used. If the old file 
name was OLDFILE, the question is: 

Use OLDFILE? 

Responses starting with an N return control to the monitor. Responses starting with Y 
will save the file under the old file name. Any other response repeats the prompt. 

SWITCH XXX, yyy - Switch Files 

The order in which xxx and yyy are listed in the catalog is switched. 

TAB - Set Tab Line 

This command allows the tab controls used by the text editor to be changed. After 
typing this command, the current tab stops are printed on the screen. The Input cursor 
Is placed In column one of the tab line. Keys from the following table are accepted as 
Input. Numbers that are entered become part of the new tab line. 

Go right one space (stops In column forty of the second line). 

<=> Go left one space (stops In column one of the first line). 

RETURN Exits the tab mode, replacing the existing tab line with whatever Is on the 
screen. This may be entered from any column. 

0 Tab skip. The editor tab command skips overall columns containing a 0 in the 

tab line. 

1 Tab stop. The editor tab command stops at the next 1 in the tab line. 

2 End of line. Editor input past the column with the 2 in the tab line is not 
permitted. The cursor will no longer be advanced after a character Is entered. 

If an eighty column printer is being used, it is recommended that the tab stop be placed 
in or before column fifty-nine, since the assembler makes use of twenty-one columns 
for Its own output. 

TIME - Print Current Time 

If a clock calendar card has been installed in the system, the current time is printed on 
the screen. Regardless of whether or not there is a clock calendar card, the current date 
is printed. 
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UNLOCK XXX - Unlock File xxx 

Unlocks file xxx, so that It may be deleted or changed. This command is equivalent to 
the DOS command of the same name. 

USER - User Command 

This command calls the subroutine SUSER, located in the operating system. The line 
typed (with leading blanks removed) is located at $200. This allows a customized 
command to be set up which may be executed from the monitor. 

In the copy of the operating system as distributed, the routine at SUSER allows the 
number of active drives to be temporarily changed from one to two. If the operating 
system is re-assembled, however, SUSER will assemble to an RTS instruction. 

VOLUME X - Set Volume Number 

The ORCA/M operating system makes frequent use of the volume number recorded on 
the volume table of contents (VTOC), located at track seventeen, sector zero. A disk’s 
volume number Is set up by the DOS INIT command. Quite often, disks are initialized 
without specifying a volume number, in which case It defaults to volume 254. Since a 
disk’s volume number is used by the system to Identify assembler input and output files. 
It Is desirable to be able to set a given disk to a unique volume number. This command 
changes the volume number in the VTOC to x. 

Note that this does not change the volume number recorded in the header of each 
sector. To change that number, the disk would have to be re-initialized. This means that 
after the volume number has been changed using this command, the ORCA/M system 
and Apple DOS report different volume numbers, becausethe VOLUME command only 
alters the volume number recorded in the VTOC. Apple DOS makes use of the volume 
number recorded in the sector headers instead. This difference should not cause any 
problems; both systems will be able to use the disk normally, excepting their different 
volume numbers. 

Setting the Language 

In addition to the above commands, the name of any computer language which has 
been identified to the operating system Is accepted as a monitor command. Unlike the 
above commands, the name of a language cannot be abbreviated. The effect of the 
language command Is to set the language number In the source file header. It also 
causes the translator program file of the current file name (i. e., ASSEMBLER) to be 
loaded in response 

If no language command is used, all files are assumed to be 6502 assembler language 
source code files. 


For instructions on adding a language name to the operating system, see appendix G. 
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Chapter Three 
The Text Editor 

Learning to Use the Text Editor 


The editor will be used by two quite different groups of people: those who have used full 
screen text editors, and those who have only used line editors. Those who have never 
used a full screen editor before are advised to go directly to the tutorial on page 37, and 
practice the commands introduced there without bothering to read the beginning of 
this chapter yet. After the editor has been used long enough for the concepts and 
commands covered in the tutorial to become comfortable, come back and read the rest 
of this chapter. 

Those who have used full screen text editors might do well to scan the tutorial anyway. If 
the material covered seems familiar, go ahead and study the main section of this 
chapter. If not, be sure and work through the tutorial using the computer. 

In either case, the reference card and appendix C will be helpful. Both have a list of all of 
the text editor commands. 


Text Entry 


Upon entering the text editor, (using the monitor EDIT or NEW commands), the user Is 
presented with a screen which can display twenty-two lines of text. These are the first 
twenty-two lines of the text file in memory; if there is no file in memory, the screen is 
blank. The memory area occupied by the text file is called the text edit buffer. The 
twenty-two lines displayed occupy the text edit window. The text edit window allows 
examination of any twenty-two contiguous lines in the text edit buffer. 
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What is seen in the window is exactly what is in that area of the text edit buffer. Text is 
entered into the text edit buffer as keys are typed. Any keyboard character may be 
entered as text except for the special function keys ESC, CTRL, SHIFT, REPT, 

RETURN, and RESET). Keystroke sequences listed In this chapter also allow entry of 
the non-keyboard characters [, ], {, }, _, | and\. 

The character typed replaces whatever character (If any) was at the cursor position, and 
the cursor advances one space. There are two case when the cursor does not advance: 
either the print stop option has been used in the tab line (see the description of TAB on 
page23), orthe cursor was in column eighty. In either of these cases, the cursor remains 
In Its old position. 

The text editor allows entry of eighty column lines of source code. Since the standard 
screen is only forty columns wide, the screen must be able to follow the cursor. As the 
cursor leaves the screen to the left or right, the display Is shifted twenty columns In that 
direction. (This feature may be turned off.) 

Using morethan fifty-ninecolumns will cause wrap-around when the assembled output 
is sent to an eighty column printer; for this reason, there is an end of line marker in 
column fifty-nine. If morethan fifty-ninecolumns are being used, resetthetab line. This 
would normally be done only if a printer that will print more than eighty columns on a 
line is being used. 

For those who have an eighty-column board, the text editor can interface with most of 
them. A routine is inculded with the system to configure it for use with a Videx eighty- 
column board. For other eighty-column boards, see appendix G for Instructions on how 
to write a driver for a given board. 

The special function keys have slightly different uses than are found when line-editing 
In BASIC; they are described below: 

0=3 Moves the cursor one space to the left. If the cursor was in column one, the 

key is ignored. 

i=> Moves the cursor one space to the right. The key is ignored if the cursor 

started in column eighty or if the cursor was on an end of line marker. 

ESC The ESC key is used for special editor functions. These are described 
starting on page 31. 

CTRL The control keys are used for special editor functions. These are described 
starting on page 28. 

SHIFT The SHIFT key allows entry of upper-register keyboard characters Note that 
In the uppercase-only mode, SHIFT M gives a ] character. If the shift key 
modification has been made, using SHIFT will give capital letters when In the 
lower-case entry mode. 
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REPT The REPT key allows a character to be entered several times without 
requiring that the key be pressed several times as well. To use this feature, 
begin by holding down the key to be repeated. Next press the REPT key. The 
effect is like repeatedly typing the original key. 

RETURN The return key places the cursor at the beginning of the next line. If thecursor 
started on the bottom line of the page, the text window is scrolled up before 
the return Is Issued. It is simply a cursor movement key and has nothing to do 
with terminating a line. 

reset The RESET key returns control to the ORCA/M monitor. (On non-autostart 
ROM models, control is returned to the Apple monitor.) The text edit buffer is 
left Intact, but recent changes may not have been entered. It is therfore poor 
form to exit the text editor via the RESET key. msf'eo.c/-) 


User Buffers 


The Copy Buffer 

The copy buffer Is a special area of memory used to temporarily store lines of text. Up to 
ninety-nine lines may be stored. Text is moved to the copy buffer using the copy and 
delete commands (see page 36.) When these commands are used, the old contents of 
the copy buffer are replaced. 

After text has been placed In the copy buffer, CTRL P is used to pop the lines into the 
text file at the cursor location. These commands allow text to be duplicated in several 
places or moved from one place to another. 

Saving and loading files does not disturb the copy buffer. 

The String Buffers 

The string buffers are memory reserved for storing the search and rep/ace strings. They 
are filled using the ESC * and ESC: commands (see page 35). The * string can then be 
searched for using CTRL Z and CTRL X, and replaced with the : string using CTRL C 
and CTRL V. 

The Character Buffer 

The character buffer is a 256 byte area used to save characters deleted using ESC <=>. 
ESC <=> recovers the characters, placing them at the cursor location. 
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Control Characters 


Control characters are immediate-response function keys in the text edit mode. This 
means that as soon as they are pressed, the function that they are used for is performed. 
To execute a control key function, first press CTRL, and, while holding It down, press 
the desired alpha key. Note that the REPT key can be used to repeat the function several 
times. 

Cursor Movement Keys 

CTRL S - Tab Left 

The cursor moves to the left until a tab stop is found in the tab line, or until It comes to 
the left edge of the page. 

CTRL A - Tab Right 

The cursor moves to the right until a tab stop or end of line marker is found in the tab 
line, or until the end of the line is reached. 

CTRL E - End of Line 

The cursor is moved to the first space past the last character in the line. If the character 
in column eighty is not a blank, the cursor is placed In column eighty. This allows 
continuation of a line easily. If an end of line marker is coded in the tab line, the cursor 
will not be placed past that marker. 

CTRL W - Start of Line 

The cursor is moved to the beginning of the line that it is on. 

CTRL T - Top Home 

The cursor is moved to the first column In the top line of the current display window. 
CTRL B - Bottom Home 

The cursor is moved tothe first column inthe bottom llneof the currentdisplay window. 
CTRL F - First Line 

The display window Is moved to the first twenty-two lines of the current text edit buffer. 
The cursor Is then placed In column one of line one. 


CTRL L - Last Line 
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All blank lines are removed from the end of the current text edit buffer. Next, the display 
window is moved to the last twenty-one lines in the text edit buffer, placing a blank line 
at the end of the file (and thus at the bottom of the display window). Finally, the cursor Is 
moved to column one of the bottom line of the display window. 

This command Is generally used to jump to the end of afileto add newtextto a partially 
completed source file. 

String Search Commands 

The following commands are used to locate any sequence of characters in a file. The 
string that is being searched for should have already been entered using the ESC 
command *, although a chance Is given to enterthe string if one Is not found. (See page 
35.) If search and replace commands are used, the : string is used as the replace string. 


CTRL Z - Search Up 

A search for the current string is made. The search starts at the line immediately above 
the line occupied by the cursor, and continues up until the string is found or until the 
beginning of the file is reached. If the string Is found, the display window Is moved so 
that the line with the string is at the top of the page, then the cursor is moved to the 
beginning of the string. If the string Is not found, the message 

String Not Found 

is printed just below the display window. If there was no string in the string buffer, the 
string entry routine is entered before the search starts. 

CTRL X - Search Down 

This command is identical to the search up command (CTRL Z) except that the search 
is conducted from the first line following the cursor to the end of the file. 

CTRL C - Search and Replace Up 

The search and replace sequence begins with the question 

Auto or manual (A or M) ? 

If a response of A is given, a string search up is conducted for the * string. If the string Is 
found, it is replaced with the : string; If It is not found the process ends with the cursor In 
its original position. After replacing a string, another search is conducted until all 
occurrences of the string have been found and replaced. 

If a response of M is given, each successful search Is followed with the question 
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Replace? 

Typing N continues the search without replacing the string. Typing Y replaces the 
string, then continues the search. Typing Q terminates the search without replacingthe 
string. 

If a search and replace is started with no string in the : buffer, the message 

Replace with null string? 

appears on the prompt line. Replying with N allows entry of the : string, while Y results 
in a search and delete. 

CTRL V - Search and Replace Down 

This is identical to search and replace up, except that the string search is conducted 
down in the file. 

Miscellaneous Commands 

CTRL D - Delete to End of Line 

This command clears the line occupied by the cursor from the cursors position to the 
end of the line. 

CTRL G - Shift display window 

The page is shifted to the right by twenty columns, displaying the next forty columns of 
text. If the command Is used while the last forty columns are being displayed, the 
display is shifted to the first forty columns. The “follow cursor” mode Is turned off. (See 
CTRL Y below.) This command has no effect if an eighty-column board is being used. 

CTRL I - Toggle Display 

If no lower-case adapter is available, the text editor defaults to displaying upper-case 
letters only. Typing CTRL I switches the display mode, causing upper-case letters to be 
displayed as inverse characters, and lower-case letters to be displayed as normal 
capital letters. 

If a lower-case display is enabled, this command has no effect. See appendix G for 
instructions on enabling the lower-case display mode. 

CTRL K - Left Bracket 

A [ character Is typed on the screen at the cursor location. Note that SHIFT M gives the ] 
character. 


THE TEXT EDITOR 


31 


CTRL N - Toggle Return Mode 

Normally, typing the RETURN key returns the cursor to the beginning of the next line. In 
anticipation of compilers for block structured languages, this option changes the return 
function so that RETURN goes to the next line, placing thecursoronthefirst non-blank 
character. If the line Is blank, the cursor goes under the first non-blank character in the 
line above. If all of the lines on the screen abovethe cursor are blank, the cursor goes to 
the beginning of the line. Typing a CTRL N asecondtime restores the original handling 
of the RETURN key. 

CTRL O - Shift Lock 

When the text edit mode Is entered, the keyboard responds with capital letters. Using 
CTRL O switches the response to lower-case letters. In the lower-case mode, the shift 
key modification will give capital letters. A second CTRL O gives shift lock again. Note 
that the assembler demands capital letters. The lower-case mode is generally used only 
for output statements. Lower-case letters will not cause problems if they are used in 
comments. 

CTRL P - Pop Lines 

All lines in the copy buffer are popped onto the screen beginning at the cursor position. 
Old lines are moved down to make room for the new lines. The copy buffer is 
unchanged. 

CTRL Q - Quit 

This command exits the text editor, returning to the monitor. 

CTRL R - Remove Blank Lines 

All blank lines, beginning withthe llneoccupled by thecursorand continuing tothefirst 
non-blank line, are deleted from the text edit window and the text edit buffer. 

CTRL Y - Toggle Cursor Mode 

When the edit mode is entered, the screen will automatically shift to keep the cursor on 
the screen. Typing CTRL Y or using CTRL G switches this mode off, so that the screen 
stays fixed on a particular forty columns of text. Typing CTRL Yagain allowsthecursor 
to be followed. This command has no effect if an eighty-column board is being used. 

Escape Key Commands 

When the ESC key is pressed, the message 


»> ESCAPE «<1 
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appears on the bottom line of the screen, two lines below the edit window. This 
indicates that the editor has entered the escape mode. The message remains there until 
the escape mode is exited by pressing any key that does not correspond to an escape 
mode command, such as RETURN or ESC. 

Escape mode commands are executed as soon as the key corresponding to the 
command is pressed. After most commands, the editor remains in the escape mode 
after the command is executed, allowing for the use of the REPT key to execute escape 
commands several times. String entry commands return to the edit mode after the string 
has been entered. 

Because the escape mode can remain active across several commands, when the ESC 
prefix is listed with the command names below, it is bracketed. This indicates that it not 
(necessarily) keyed before the command key is typed, only that the escape mode must 
be active. 


The Repeat Feature 

Escape commands may also be repeated by setting a repeat count. This Is done by 
typing a decimal number, followed by any valid ESC command. The command is then 
executed the Indicated number of times, to a maximum of 255. 

An example would be the Insertion of fifty lines at the current cursor location. First, the 
escape mode Is entered by pressing ESC. Then the number 50 is typed (there is no 
screen echoing of repeat counts). Next, press the command key corresponding to 
inserting a line (M). Fifty blank lines are now placed In the text edit buffer, several of 
which can be seen in the edit window. Finally, the edit mode is re-entered by pressing 
the ESC key. 

If a number larger than 255 is entered, or If the ? character Is used, the next command 
will be executed as many times as possible. For commands like Inserting a line, which 
have no theoretical limit on the number of times they can be performed, 256 Is used. 


Cursor Movement Commands 

[ESC] I - Move Up 

Moves the cursor up one line. The screen is scrolled up to accommodate moving the 
cursor if the cursor was on the top line of the text window. If the cursor was on the first 
line In the file, the command is ignored. 


[ESC] J - Move Left 
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The cursor is moved left one column. If it started in column one, the command Is 
Ignored. 

[ESC] K - Move Right 

The cursor Is moved one character to the right. If it starts in column eighty or on a print 
stop, the command is ignored. 

[ESC] M - Move Down 

Moves the cursor down one line, scrolling the page if necessary. Blank lines are added 
at the end of the file If they are needed. 

Text Edit Window Controi 

[ESC] E - Scroll Up One Line 

Scrolls the current text window page upone line, placing thecursoronthe next lineup. 
The cursor remains in the same relative position on the screen that it started at. 

[ESC] C - Scroll Down One Line 

Scrolls the current text window down one line, placing the cursor on the next line down. 
The cursor remains in the same relative position on the screen that it started at. 

[ESC] W - Scroll Up One Page 

Moves the edit window to the twenty-two lines immediately before the lines in the 
current display window. The cursor Is left in the same position in the window that it 
started. 

If the beginning of the file is less than twenty-two lines up, the edit window is moved to 
the beginning of the file. 

[ESC] X - Scroll Down One Page 

This is the same as scrolling down one page, except that the page after the one in the 
window Is displayed. 

Insert and Delete 

[ESC] B - Insert Line 

Inserts a blank llneatthe position of the cursor, moving old lines down to make room for 
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the new one. 

[ESC] Y - Delete Line 

The line that the cursor is on is deleted, moving the following lines up to fill the space. 
[ESC] H - Insert Character 

Inserts a space at the position of the cursor, moving the rest of the line to the right to 
make room. Characters scrolled off of the right side of the line are lost. 

[ESC] G - Delete Character 

The character under the cursor is deleted, moving the rest of the line to the left to fill the 
gap. A blank is Inserted at the end of the line. 

Non-keyboard Characters 

Non-keyboard characters may be entered In the escape mode using the following 
translation characters. Most of these special characters will be displayed correctly only 
If a lower-case adapter or eighty-column board is installed. 

[ESC] / Backward Slash (\) 

In the escape mode, this key produces its reflection. 

[ESC] _ Underline (_) 

The underline character is entered on the screen. 

[ESC] + Tilde (~) 

The tilde character Is entered In the screen. If a lower-case adapter is not used, the tilde 
is displayed as the upward arrow character. 

[ESC] ! - Vertical Bar (|) 

The vertical bar is entered by typing an exclamation mark in the escape mode. 
[ESC] ( - Left curly bracket ({) 

The left curly bracket may be entered by typing a left parentheses. 

[ESC] ) - Right curly bracket (}) 
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The right curly bracket is entered using the right parentheses. 

[ESC] < - Left square bracket ([) 

The left square bracket Is input via the left angle bracket. 

[ESC] > - Right square bracket (]) 

The right square bracket is Input with the right angle bracket. (The right square bracket 
may also be entered in the edit mode by typing CTRL K.) 

[ESC] % - At sign (@) 

The at sign, which cannot be entered In the lower case mode using SHIFT-P If the shift- 
key modification is installed, is entered in the escape mode by typing the percent key. 

[ESC] " - Up arrow ( f ) 

The up arrow likewise cannot be entered using shIft-N with the shift-key mod active; use 
the quote mark in the escape mode. 

Buffer Commands 

[ESC] * - Enter Search String 

This command puts the cursor just below the current display window, following 
an * prompt. Any string valid in the edit mode may then be entered, finishing with a 
RETURN. This enters the string Into the search string buffer for use by the search 
commands (see CTRL X and CTRL Z above). If RETURN is entered immediately, any 
existing search string is cleared from the buffer. 

While entering the string, four special characters are recognized. They are the left and 
right arrows, RETURN, and CTRL O. The left and right arrows move the cursor left and 
right, erasing or entering the characters they pass into the input buffer. Characters 
erased from the Input buffer using the left arrow remain on the screen, as they do when 
the monitor is in use. The RETURN key ends the string at the current cursor location. 
CTRL O Is the shift lock toggle, as In the text edit mode. The shift key modification is still 
supported. Although the display mode cannot be changed while entering a string, the 
display mode set in the text editor is used when displaying the string. Embedded, 
leading and trailing blanks are allowed, and are significant. 

[ESC] : - Enter Replacment String 

This is the same as entering a search string except that the resulting string Is used to 
replace the search string using the search and replace commands. 
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[ESC] O - Delete Lines to Buffer 

The line containing the cursor is moved to the copy buffer, replacing the previous 
contents of the buffer. The line is then deleted. The line deleted may then be placed 
elsewhere using the pop command (see CTRL P above). 

Using the repeat count allows more than one line to be placed In the copy buffer, 
beginning with the line occupied by the cursor. The lines copied are then deleted from 
the text edit file. A maximum of ninety-nine lines may be deleted at one time. 

The copy buffer Is fairly permanent. An assembly, link edit, compile or execution of a 
program (using BRUN ) will erase It. So long asthe user remains in the monitor and text 
editor only, the only way to change the copy buffer Is to use ESC O, ESC P, or from the 
monitor, the COPY or COMPRESS commands. 

[ESC] P - Copy Lines to Buffer 

This is the same as the delete lines to buffer command above, except that the lines 
moved to the copy buffer are not deleted. This allows copying sections of code to other 
locations. 

[ESC] F - Display Core Used 

This displays the current percentage of the text buffer in use. See page 19 for comments 
on the percentage of memory in use. 

[ESC] O Delete a Character to the Buffer 

The character to the left of the cursor Is deleted from the screen and placed in the 
character buffer. The cursor and all characters from the cursor to the end of the lineare 
shifted one column to the left to fill in the vacated space. A blank is placed at the end of 
the line. 

If more than 256 characters are placed in the buffer, the oldest characters are lost. 
[ESC] >=> Insert a Character from the Buffer 

The last character deleted to the character buffer is removed from that buffer and 
placed at the current cursor location. Characters from that position to the end of the 
line, including the cursor, are shifted one column to the right to make room for the new 
character. Characters shifted off of the end of the line are lost. 


If more characters are inserted from the buffer than were put in, blanks are Inserted. 
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Text Editor Tutorial 

What follows is a guided tour through the most useful text edit commands. Not all 
commands are covered here, and not all capabilities of the commands listed are dealt 
with. Enough information is given to learn how to enter normal assembly language 
programs. After mastering this material, the detailed descriptions of the commands 
given at the beginning of this chapter should be studied. 

To begin, place the SYSTEM SOURCE disk on line, and load the file FOPRS.SBLOD. 
Now enter the text editor by typing E, followed by RETURN. 

Moving Through the File. 

The display will clear and the first twenty-two lines of thefileappearonthescreen. One 
of thefirstthingsto learn howto do is to movefrom one place in thefileto another. To do 
this, the escape mode is entered. The editor runs In two modes: edit and escape. The 
escape mode is simply a way of making more commands available than there are keys 
on the keyboard. It works very much like the l-J-K-M escape key commands in the 
Autostart ROM. 

Press the ESC key. At the bottom of the screen, the message 

»> ESCAPE «< 

appears to indicate that the escape mode has been entered. This message stays there 
for as long as the escape mode is active and vanishes upon return to the edit mode. 
Leave the escape mode now by keying ESC again. Any key that is not an escape mode 
command key (for example, ESC ) causes the escape mode to be exited. 

Re-enter the escape mode (by using ESC again) and type X. A RETURN is not needed. 
The screen will change to show the next twenty-two lines of text. Now type a W. This 
moves the display back to the first twenty-two lines of text. Notice where the keys are on 
the keyboard. Think of the screen as a window which is laid on a giant scroll; it makes 
sense to use a top row key like W to move toward the beginning of the file and X to move 
toward the end. Try these commands a few times to get a feel for them. 

Just to the right of the W and X keys are the E and C keys. These move the text window 
one line, instead of one page. Try them. 

At this point, the screen can be moved up and down in the file. Cusor movement is next. 
Just as with the autostart ROM, the I, J, K and M keys move the cursor. Note that these 
keys are placed on the keyboard in a diamond, their positions indicating the direction 
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each key moves the cursor in. Try them out. Also try and move the cursor off of the 
screen in each direction, and see what happens. The REPT key may be used with these 
keys. When using the keys, notice that J will not move the cursor to the left of the first 
column. K is similarly limited by the end-of-line marker in the TAB line, which is set to 
column fifty-nine. I cannot move the cursor beyond the top of the first line in the file. 
However, M will continue to move past the end of the file, adding blank lines to the end 
of the file. 

Having moved to the end of the file using the M key, It would be nice to haveaquick way 
to get back to the start of the file. One way to do this Is to use the repeat feature. While in 
the ESC mode, press the 9 key. Nothing happens. Now press W. Instead of moving up 
one page, the screen scrolls up nine pages. Numbers up to 255 may be entered in this 
manner. This feature will work with any ESC command; in fact, the grouping of 
functions as either escape commands or control key commands was largely 
determined by selecting those commands which could most benefit from having the 
repeat feature available to them. 

At this point, one should be somewhat adept at moving trough the file In memory. There 
are a few other movement commands that are very useful, but they are used from the 
edit mode. Get back into the edit mode (using ESC ) and try CTRL F and CTRL L. This 
jumps to the beginning or end of afile in onestep. Notice that these keys are not located 
geographically; instead, they were assigned mnemonically. CTRL F stands for first line, 
while CTRL L stands for last line. Now try CTRL T and CTRL B. These commands move 
to the top and bottom of the display window. Finally, CTRL E moves to the end of a line, 
and CTRL W, located to the left of E, moves to the beginning of a line. 

The next feature for moving the cursor Is the tab function. The tab keys are CTRL A and 
CTRL S. Because a tab right is probably the most frequently used cursor movement key, 
it has been assigned CTRL A. This makes it easy to type It with one hand. Try It a few 
times. Moving to the left is accomplished using CTRL S. Try this one, too. 

It may seem counter-intuitive to tab left using the key tothe right of thetab right key. It Is 
actually easier and faster to type CTRL A. Since this is done an average of three times 
for each assembly language instruction, the reversal of direction makes sense. It soon 
becomes a conditioned response. 

Finally, there are the RETURN, left arrow, and right arrow keys. The left and right arrows 
are equivalent to the ESC J and ESC K keys. RETURN places the cursor at the 
beginning of the next line down. The RETURN key Is not required to mark the end of 
each line, it is simply a movement key. 

Entering Text 

Text may be entered anytime the edit mode Is active, I.e., when one is not in the escape 
mode. Move the cursor to where the text is to be, and start typing. The keys typed 
replace the old contents of the file, and the cursor moves one space to the right. 
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Inserting and Deleting Text 

As changes are made to a file, one of the more frequently needed tasks is inserting blank 
lines and removing unwanted ones. This is done from the escape mode. 

As with the cursor movement commands, the insert and delete commands are 
geographically oriented. The diamond of keys immediately to the left of I, J, K and M Is 

Y, G, H and B. 

To delete a line, begin by placing the cursor on it. It doesn’t matter where in the linethe 
cursor is located. Press Y from.the escape mode. The line vanishes, and the following 
lines are moved up one line to fill in the space. The repeat feature also works; to delete 
twelve lines, type 12Y. The twelve lines starting with the line that the cursor is on are 
deleted. The lines do not have to be on the screen to be deleted. 

Inserting blank lines is similar. When B is hit in the escape mode, a blank line is inserted 
at the location of the cursor. The line that the cursor was on and all of the lines after it are 
moved down to make room for the new line. Again, the repeat feature works. 

To Insert characters, place the cursor at the place that a new character is desired. The H 
key will cause all characters from the cursor position on to be shifted to the right one 
character. A blank Is placed at the cursor position. Try this enough times to cause a 
character to go off of the end of the line. Remember that the line is eighty columns wide, 
even If the display only shows forty columns. Now use the G key to delete one of the 
blanks just inserted. A blank appears in the last column. This emphasizes that 
characters scrolled off of the end of the line are lost. 

One of the more common uses of the line insert capability is to make room for large 
additions to source files. The cursor is placed appropriately, then a few hundred lines 
are Inserted, followed by a stream of text. There will undoubtedly be some extra blank 
lines left over. Typing CTRL R from the edit mode removes these lines, beginning atthe 
cursor position and continuing to the first non-blank line. 

To see how this works, insert fifty blank lines. Now move the cursor down a couple of 
lines, and enter the edit mode. Type CTRL R. 

Moving and Copying Text 

Three commands allow text In a file to be moved or copied in increments of one line. 
This involves the use of the copy buffer. The copy buffer is an area in memory set aside 
to hold up to ninety-nine lines of a source file. 

As an example, place the cursor on a line to be copied. Enter the escape mode and type 
P. Now leave the escape mode and type CTRL P. What happened? 

A line has just been pushed into the copy buffer, and popped back off. The same thing 
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can be done with multiple lines. Enterthe escape mode and type2P.Nowgobacktothe 
edit mode and type CTRL P. Continue typing CTRL Pa few more times. Move the cursor 
up a few lines and type CTRL P again. 

The point is that popping lines from the copy buffer does not delete them. The same 
lines can be popped at various locations until the copy buffer is changed by pushing a 
different line (or lines) into the copy buffer. 

The third command is CTRL O. This works like CTRL P, pushing lines into the copy 
buffer, with a key difference. After the lines have been pushed into the copy buffer, they 
are deleted from the source file. This allows text to be easily moved from one place in the 
file to another with a minimum of keystrokes. 

Single characters can also be removed from the file and placed in another buffer, the 
character buffer. Unlike the copy buffer, thecharacter bufferfunctions likeatruestack. 
Enter the escape mode and press the left arrow key a few times. Now try the right arrow. 
Try replacing more characters than were entered. 

As characters are deleted from the file using the left arrow, they are placed in the 
character buffer. As the right arrow is used to retrieve them, they are removed from the 
buffer. Placing more than 256 characters in the buffer starts to delete the oldest 
characters. Retrieving more characters than were put In places blanks on the screen. 


Search and Replace 

The last featureof theeditorto beexamined here isoneof the most useful and powerful. 
The editor is capableof searching forstrings in the source file and replacingthem with a 
different string. 

Enter the escape mode and type an asterisk (*). An asterisk is shown at the bottom of the 
screen, followed by the cursor. Type END, followed by a RETURN. Notice this causes a 
return to the edit mode, rather than remaining in the escape mode. 

A search string has just been entered. It remains valid until a different search string is 
entered. Typing a CTRL X will move the text window so that the next occurrence of the 
search string in the file appears on the top line, with the cursor placed at the start of the 
last occurrence of the search string In that line. CTRL Z does the same thing, but 
searches toward the beginning of the file instead of toward the end. Try these 
commands, paying special attention to what happens when the string Is not found. 

Replacing the search string with a replace string Is almost as easy. From the escape 
mode, type a colon (:). Again, the prompt appears at the bottom of the screen. Type FIN 
and a RETURN. This enters a replace string. CTRL V initiates a search and replace 
starting at the current cursor location and proceeding down In the file, while CTRL C 
does the same going up in the file. Try one of these commands. 
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After entering either command, the editor asks if an automatic or manual search and 
replace should be done. An automatic search and replace replaces every occurrence of 
the search string with the replace string. For now, try a manual search. After entering 
the M, if the search string is found, the line containing it is placed at the top of the 
screen. At the bottom is the question 


Replace? 

Any reply starting with Y replaces this occurrence of the search string with the replace 
string. N will skiptothe next occurrence ofthesearch string without changingthis one. 
Q quits the search and replace mode. 

Experiment with these commands for a while. Pay close attention to results when the 
search string cannot be found. Also, be sure and try search and replace commands with 
search and replace strings of different lengths, and with blanks at the beginning and 
end of the strings. 

After these commands have become familiar through practice, refer to the beginning of 
this chapter for a full description of all of the editor commands. 
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Chapter Four 
The Assembler 

Section One 
Running the Assembler 


Introduction 


This chapter describes how to use the ORCA/M macro assembler. This first section 
begins with introductory material and concludes with a description of the assembler 
command parameters. The format and directives used for coding source lines is 
explained in the succeding sections. 

The assembler is the heart of the ORCA/M assembly language development system. It 
is invoked from the monitor by using any of theassembleor compilecommands. Itthen 
assembles the source file in the text edit buffer. 

The assembly is not limited to the source file in memory. For large programs, the file in 
memory is simply the first of many source files. Thefile in memory chains to or includes 
other source files using APEND and COPY assembler directives. The needed source 
files are brought Into memory automatically. After the assembly is finished, the original 
source file is loaded back into the text edit buffer. 

If macros are used, one or more macro files will be needed by the assembler. When an 
operation code is encountered in a source file which does not match any 6502 
Instruction or assembler directive, the macro files are scanned for a macro definition. 
The macro, if found, is then expanded into the source stream and assembled into an 
output file. Both the source file itself and macro file remain unchanged. 
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Memory Organization 

The following memory map presents the organization of memory as used by the 
assembler. The source file to be assembled is expected in the text edit buffer (where it 
has been created by the editor or loaded from disk with the LOAD command.) The 
program buffer is used to save object modules generated by the assembler. It Is spooled 
to disk as it is filled up, sothat programs of any length can be assembled. 


Assembler RAM Usage 

All addresses are in hexadecimal 


Usage 

48K System 

64K System 

Page Zero 

OOOO-OOFF 

OOOO-OOFF 

Stack 

0100-01FF 

0100-01 FF 

Work Space 

0200-03FF 

0200-03FF 

Text Screen 

0400-07FF 

0400-07FF 

Assembler 

0800-58FF 

0800-58FF 

Code Build Buffer 

6100-68FF 

5900-68FF 

Work Space 

6900-6FFF 

6900-6FFF 

Text Buffer 

7000-8FFF 

7000-8FFF 

Macro Buffer 

9000-AFFF 

9000-AFFF 

Operating System 

BOOO-BFFF 

BOOO-BFFF 

Symbol Table 

5900-60FF 

D000-F7FF 


The SYS FIRST Disk File 

When the assembler encounters the first COPY or APEND statement, it saves the file in 
memory on the last disk accessed, under the name SYSFIRST. This is done to preserve 
the original file for reloading before control is returned to the monitor. The name 
SYSFIRST is thus a reserved file name for the use of the assembler, and any other file of 
that name is in danger of being destroyed by the assembly process. 
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Normally, theSYSFIRST file is deleted atthe end of the assembly process. IftheRESET 
key was hit during an assembly, or If a terminal assembly error was encountered, this 
file may not be deleted. If it is left on the disk by the assembler. It can be deleted 
manually. Otherwise, it will be deleted after the next normal assembly. 

Disk Access 

The assembler does not need to be given slot or drive parameters for any of its 
operations. It searches all active drives for a given volume number. If the needed volume 
Is not located, the assembler will print a message like 

Place Volume 67 Online 

and then pause and wait for a key to be pressed. After a key is pressed, it repeats the 
search process. 

All active disk drives should contain a disk during assembly. If they do not, the 
assembler may try to access the drive during a search for a volume, generating a disk 
I/O error, which Is a terminal error. When the assembly is completed, the operating 
system expects to find the system disk with the file MONITOR in the slot and drive 
specified as the system drive during configuration (the default Is slot six drive one). If 
the operating system does not find the monitor it will ask for the system disk to be 
placed in the system drive. 


The Assembly Process 


Pass one 

The source file Is assembled one subroutine (program segment) at a time. Each 
subroutine goes through two passes. Thefirst pass resolves local labels. When pass one 
encounters an END statement ortheend of thesourceflle, it passes control to pass two. 

Pass two 

When pass two is called, it starts with the same line that pass one started at. Pass two 
then assembles each line for the last time. Pass one has already resolved any local 
labels, so pass two can produce both the object code output and the assembly listing. 
External labels are resolved as $8000, possibly with some offset value. External zero 
page labels, indicated in the source listing by square brackets surrounding the label 
name, are resolved as $80. 
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When pass two finishes with a subroutine, it printsthe local symbol table. Itthen passes 
control back to pass one to begin the next subroutine. If there are no more subroutines 
to assemble, control Is returned to the operating system. Depending on the “assemble” 
command given, the operating system passes control to either the monitor or link 
editor. If the link editor Is called, it uses the object modules created by the assembler as 
input. These are relocated and global labels are resolved, giving an executable binary 
file as output. 

Controlling the Speed 

This assembler has a throttle: paddle zero can be used to slow down the assembly 
listing as pass two prints it. This is desirable when If the screen output only is being 
scanned, rather than using the PRNT ON directive to create an assembly listing on a 
printer. To slow down the listing, turn paddle zero counterclockwise. Speed can be 
recovered by turning the paddle clockwise. 


Stopping the Listing 

At any time during pass two, the assembly may be stopped by pressing any keyboard 
character. Note that the assembly will stop only if a line or symbol table Is being printed, 
and not for the pass headings (which lists the subroutine name). This provides a quick 
way to scan for errors; by turning off the listing and symbol table, only the output of 
error lines can stop the listing. Pressing a key at the beginning of the assembly will then 
stop the listing at the next error. Since the pass headings are stIILdisplayed for each 
subroutine, the subroutine which contains the error may be determined. 

To restart the listing, any key but ESC may be pressed. The listing will continue until 
another key is pressed to stop It again. If the listing has been stopped, and ESC is 
pressed, the text editor is entered. The last line printed will beatthetopof theedit page, 
with the cursor at the beginning of that line. 

Terminal Errors 

If the assembler encounters a terminal error (such as a symbol table overflow), it prints 
the error message and waits for a key to be pressed. Then it returns control to the 
operating system. The operating system enters the text editor automatically, and places 
the line that caused the error at the top of the text edit window. This allows identification 
of the offending line, even if pass two had not started and no listing had been produced 
yet. 

A list of terminal errors is contained In appendix A. 

The RESET Key 

If the RESET key is pressed during an assembly, control Is returned to the operating 
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system. The operating system enters the text editor as if a terminal error has occurred. 
The editor is entered, and the current line is displayed, showing where the assembly 
process had been Interrupted. If this was done during a macro resolution, the line 
displayed is the macro call statement. 


The Assembly Listing 


It may be helpful to refer to Listing One at the end of the manual for examples of 
assembler output while reading this section. 

Screen Listings 

A listing on the screen Is produced during pass two unless the assembler is instructed 
not to list the output. Each subroutine begins with two messages announcing the 
subroutine name and pass. The listing continues with the assembled code. 

Each output line has three parts. The first part Is the current relative address. This is the 
memory location that the code would be at if the subroutine were placed at location 
$0000 by the link editor. (Despite this offset, labels defined relative to the program 
counter within the range zero to $FF are not zero page; the origin of $0000 Is simply for 
convenience in calculation. Internally, the actual origin in the relocatable object 
module Is $1000. The link editor outputs indicate where the subroutine Is actually 
located in a given binary file.) Next comes a sequence of up to three bytes, printed In 
hexadecimal. This Is the code that was generated by the assembler. Finally, the source 
statement that generated the code is printed. 

If there are more than thirty-nine characters (seventy-nine with eighty-column boards) 
in the output line, it is continued on the next line of thescreen. Spaces are automatically 
generated to begin output underthe first character of the source statement from the line 
above. 

If an error is detected in the source statement, it is printed on the next line. All error 
messages are text messages, not simply error numbers. The errors are explained in 
appendix A. 

Printer Listings 

If the PRNT ON directive is issued in a source file, subsequent lines are sent to the 
printer. The assembler expects an eighty column printer with an Interface card in s\ot 
one. (Other printer slots may be configured by re-assembling the operating system.) 

Printed listings are generally the same as llstingstothe screen, exceptthat each line has 
a line number and the messages announcing the start of various passes are not printed. 
The assembler assumes sixty-six lines per page, and prints on sixty of those lines. Six 
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lines are skipped after each block of sixty lines to allow for page breaks. After printing 
the symbol tables for a subroutine, the assembler skips to the top of the next page. 

As mentioned before, each linesenttothe printer starts with a line number. This is afour 
digit decimal number, starting at 0001 onthefirst lineand incrementing for each source 
line. The line number is incremented even if the output line is not printed. Thus, even if 
printing is turned off for part of the assembly, it is still possible to know exactly how 
many lines the assembler has processed. Lines generated by a macro are not 
considered source lines, so they do not have a line number. 


Assembler Parameters 

All commands which cause an assembly or compile can be followed with a number of 
parameters which set the assembler options. (Assemble and compile are equivalent. 
The operating system loads the assembler or compiler based on the language number 
contained in the file header.) Abbreviation of parameter names is not allowed. 

All of the parameters except NAMES have corresponding assembler directives. If both a 
parameter and a directive are used, the parameter setting is superseded by the 
assembler directive when the assembler directive is found in the source file. Source 
lines before the assembler directive is found will be under the control of the command 
line parameter setting. 

KEEP= XXX - Keep File Name 

This parameter tells the assembler to keep the object module it produces, that is, store 
the generated object code to disk. The disk file xxx Is used for the output file. The file 
name must not contain commas. 

LIST OFF - Don’t List Output 

The normal output from the assembler is suppressed. Only the pass messages, errors 
and symbol tables will be listed. 

NAMES=(n1,n2, ... ,nx) - Subroutines to Assemble 

The assembler will assemble only the subroutines whose names are listed. Subroutines 
are given names using the START or DATA directives, as explained in section three. 
The output object file will contain only the subroutines listed; however. It will be named 
as part of a collection of files from previous assemblies of the same source file In a way 
that allows the link editor to link files from different assemblies together. The chapter on 
the link editor describes in detail how this is done. 

Assembler directives which are global in scope will still be resolved, whether or not they 
are in one of the subroutines assembled. These directives are: 
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APEND 

append a source file 

COPY 

copy a source file 

ERROR 

print errors 

EXPND 

expand DC statements 

FPLEN 

set floating point length 

GEN 

generate macro expansions 

GEQU 

define global symbolic constant 

KEEP 

keep output file 

LIST 

list output 

MCOPY 

copy macro file 

MDROP 

drop macro file 

MERR 

maximum error level 

MLOAD 

load macro file 

MSB 

set most significant bit 

PRNT 

send output to the printer 

SYMBL 

print symbol tables 


The operands of these directives cannot contain labels unless they appear inside a 
program segment, and the segment that they appear in is assembled. If these rules are 
not followed, an Invalid Operand error will result. If they appear inside a macro, they are 
not resolved unless the macro is expanded. The directives themselves are described in 
section three. 

ORG= - Set Origin 

Assembly will begin at the fixed memory location specified tothe right of the equal sign. 
The origin may be coded in decimal or hexadecimal. If hexadecimal numbers are used, 
the number must be preceded with a $ character. 

This does not set the origin in the object modules - it is simply passed on to the Link 
Editor. To permanently set the origin, use the ORG directive instead. 

PRINT ON - Print Output 

Assembler and link editor output are sent to the printer. 

SYMBOL OFF - Symbol Table Off 
Symbol tables are not listed. 

Volume Parameter 

The volume parameter sets the volume number that the output file will be saved to. It is 
only needed if KEEP Is coded. If KEEP is coded and the volume parameter is omitted, 
the current volume is used. It is coded as a V followed by a decimal number from 1 to 
254, inclusive. The volume parameter should always be used with multi-drive systems. 






Chapter Four 
The Assembler 

Section Two 
Coding Instructions 


Types of Source Statements 


There are four types of lines in an assembly language source listing. The first Is the 
comment line. Its purpose Is to allow text to be inserted in the source listing In order to 
document the program. Two other line types are instructions and assembler directives. 
They are coded in the same way, and are described together here. The last is the macro 
call statement, detailed in section four. Examples of coded lines can be found in the 
subroutine library in listing three, and in the listing of the operating system found in 
listing one. 

Assembler source file lines may be up to eighty columns long, numbered from one to 
eighty. Since most printers use eighty columns, assembler source lines should 
generally be restricted to fifty-nine columns, as twenty-one columns must be allowed 
for Information printed by the assembler. If this Is not done, printed assembler output 
will wrap aroundtothe next line. Asidefrom makingthe listing Impossibleto read, it also 
causes the assembler to miscount the number of lines of printed output, misplacing 
future page breaks. 


Comment Lines 


There are six forms of lines which are regarded as comment lines by the assembler. 
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They are described by use. 

The Blank Line 

Any blank line is treated as a comment line. Blank lines are often used to logically 
separate sections of code. 

The Characters * ,; , and ! 

Any line with an asterisk (*), semicolon {;), or exclamation mark (!) in column one is 
treated as a comment. Any text in the line is ignored. It will be printed when the source 
listing is generated by the assembler. 

The Period 

Any line with a period (.) in column one is treated as a comment. These lines are not 
printed in the source listings produced by the assembler. These lines are intended for 
use as labels for conditional assembly branches. (See AiF and AGO in section four.) 

The Greater Than Sign 

Lines with a greater than sign (>) in column one are treated as comments. These lines 
are used as continuation lines by the assembler. They are treated as comments in case 
the assembler does not need to look for a continuation line. This might happen if there 
was an error in the previous line. This type of comment line Is printed in the source 
listing. 

It is not a good idea to usethese lines as a general purpose comment line, sincethey are 
handled internally in a different way than other lines. In particular, useof this typeof line 
as the first line In a file will cause the assembler to go into an infinite loop. 

Examples of Comment Lines 

The following examples illustrate the rules outlined above. 

! THIS SECTION SHOWS THE VARIOUS VALID 
! WAYS TO CODE COMMENTS 


* NOTE THE BLANK LINES ABOVE, WHICH ARE 

* ALSO COMMENT LINES 

> THIS LINE IS A COMMENT, BUT THE > 

> LINE IS GENERALLY USED FOR 

> CONTINUATION LINES 

; THIS CHARACTER CAN BE USED FOR 
; COMMENT LINES THAT YOU WANT TO BE LESS 
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; OBTRUSIVE THAN LINES WITH A * 

! THE FOLLOWING COMMENTS ARE NOT VALID 
* THE COMMENT DOES NOT START IN COLUMN ONE 
THERE IS NO 
COMMENT 
CHARACTER IN 
COLUMN ONE 

: THE LINE STARTS WITH AN INVALID 
: CHARACTER 

Coding Instructions and Assembler Directives 

For the purpose of coding instructions and assembler directives, the source line is 
divided into four fields. The default location of these fields is illustrated below: 


field 

label 

op code 

operand 

comment 

column number 

0000000 

001111 

1111112 

22222222233333333334 


1234667 

890123 

4567890 

12345678901234667890 


ORCA/M Is a free form assembler. This means that the starting columns of the fields 
named above are optional. They are treated as described above to facilitate discussion 
of the various parts of the line, and to facilitate standardization in code. (See the Style 
Manual for more on standardized form.) 

The fields shown above reflect the default tab settings, and are set up for six-character 
labels. Actually, the assembler can handle labels up to ten characters long. If labels 
longer than six characters are used on a regular basis, the tab stops may be shifted to 
accommodate the longer fields. The six-character limit Is basically a matter of style, so 
that the source code will fit easily on a forty column screen. 

Each line can contain Information in all of these fields. Except for comment lines, each 
line must have an operation code as a minimum. The nature of each of the fields Is 
described specifically below. 

The Label 

Each line may begin with a one to ten character label. This label is processed by the 
assembler and stored in the symbol table along with the current location counter. (The 
location counter is the address at which the instruction will be stored.) The label may 
then be referenced in the operand field of other instructions, and Is equivalent to using 
the address of the the labeled instruction. 

Labe\s must start in column one and begin with an alphabetic character. Subsequent 
characters may be any alphabetic or numeric character. Embedded blanks are not 
allowed. 
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It is generally not advisable to use the letter “A” as a label, since the assembler may 
confuse use of the label with the accumulator addressing mode. 

The following lines contain examples of legal labels: 

LABEL LDA #4 

C STA 14 

LONGESTLAB LDA 5 
V190 STA 16 

The next set of lines contain illegal labels. The comment field indicates why the label is 
not valid. 

LABELTOOLONG LDA #3 THE LABEL HAS MORE THAN 10 CHARACTERS 
1000 STA 14 THE LABEL DOES NOT START WITH AN 

! ALPHABETIC CHARACTER 

AB$ LDA #7 THE LABEL HAS A NON ALPHANUMERIC CHARACTER 

LABEL STA 15 THE LABEL DOES NOT START IN COLUMN 1 

The Operation Code 

The operation code field is reserved for an assembly language Instruction, assembler 
directive, or macro. At least one space must be left between the label and the operation 
code. If no label is coded, the operation code can begin In any column from two to 
twenty. Normally, the operation code begins in column eight. The tab line has a tab stop 
in this column for convenient placement. 

Operation code mnemonics for machine-language instructions are always three 
character alphabetic strings. These are listed In appendix B. (I n addition to the normal 
mnemonics for instructions, several "alias" op codes are allowed; see the appendix.) 
Assembler directives vary in length from two to five characters. The operation codes for 
assembler directives are listed In section three. Macro operation codes, which are a 
form of user-defined operation code, are described In section four. 

The Operand Field 

The operand Is the information that the Instruction uses to perform its function. There 
must be at least one space between the operation code and operand. The operand 
normally starts in column fourteen; a tab stop is provided to allow easy movement to 
that location. Formats for the operand field vary a great deal. Referto the descriptions of 
the Individual operation codes for the format to be used in forming their operand fields. 
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Column twenty has special signifigance for the operand filed. This is done so that 
comments on the same line with an instruction will not be required to start with a 
comment delimiter. The assembler will notsearch pastcolumntwenty forthestartof an 
operand field unless the operation code extends past column eighteen. In that case, the 
operand must start exactly one space after the operation code. 


Coding Operands for Instructions 


I nthetable that follows, ABS indicates atwo byte absolute address. The address may be 
represented in the form of a label, a number, or an expression involving several terms 
and arithmetic operations, so long as a value from $0000 to $FFFF results. Similarly, ZP 
is used to Indicate a one byte (zero page) address. 


Addressing Mode 

Operand Format 

Implied 

none needed 

Immediate 

#ZP 


#>ABS 


#<ABS 


#ABS 


/ABS 

Absolute 

ABS 

Zero Page 

ZP 

Relative 

ABS 

Absolute Indexed 

ABS,X 


ABS,Y 

Zero Page Indexed 

ZP,X 


ZP,Y 

Indirect 

(ABS) 

Indexed Indirect 

(ZP,X) 

Indirect Indexed 

(ZP) , Y 

Accumulator 

A 


Operands for the immediate addressing mode must be resolved to a single byte. The 
use of the greater than sign (>) after the pound sign (#), or the slash (/) by itself, allows 
selection of the high-order (most significant) byte of a two byte absolute address. The 
low-order byte Is specified by using the less than sign (<) after the pound sign, or is 
selected by default if # is used with a sixteen bit value. If the absolute address is an 
expression, the address is first resolved into asingletwo byte number, and then a byte is 
selected. For example, each of the following instructions result in loading the 
accumulator with a hexadecimal $E4: 
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LDA 

#$E4 

LDA 

#<|AAE4 

LDA 

#$AAE4 

LDA 

/$E4AA 

LDA 

#>fE4AA 

LDA 

#<$AAE0+4 

LDA 

#>$E0AA+$400 


A zero page address can be coded with any instruction that allows an absolute address. 
If the instruction allows zero page addressing, the assembler automatically assembles 
the Instruction that way. If zero page addressing is not allowed, the assembler resolves 
the Instruction as an absolute address with a zero high byte. 

Note that although indexing with the X and Y registers are coded similarly, not every 
Instruction allows both registers to be used as indexes. 


Coding Addresses 

As mentioned before, the absolute and zero page addresses need not be limited to a 
single constant; it may be coded as an expression. Likewise, therearea number of ways 
to code a number. Any of them may be used. Coding follows the rules detailed below. 

Labels 

When a label appears in the address field, it is resolved Into a two byte hexadecimal 
value. In the case of instructions and most assembler directives, this location Is the 
location of an Instruction or data area defined within the program. Exceptions are labels 
defined via EQU and GEQU; see section three. 

All subroutines are assembled as If starting at location $0000. (Internally, they are 
stored on disk as if starting at $1000 to avoid conflict with pagezero; the origin of $0000 
is for the programmer’s convenience In performing arithmetic relative to the actual 
starting address.) Labels defined in the subroutine will have addresses relative to this 
starting address, regardless of any PAGE or ORG directives. The run-time address for 
the label is determined later by the link editor. 

There are times when a zero page label in a data area is used later in a subroutine. Since 
the assembler has no way of knowing that the unresolved label is zero page, it must be 
told. This is done by enclosing the zero page label In square brackets. The assembler 
then assigns a temporary value of $80 to the label and flags it as zero page. If the link 
editor later finds that the label Is not zero page, it will flag It as an error. 

If a zero page label is defined using the GEQU directive. It becomes global for the 
assembly. This means that any subroutine can access the label, as if the label was 
defined using an EQU directive in every subroutine. This allows the assembler to 
automatically examine the label and determine that it is zero page. In this case, the 
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square brackets are not required around zero page labels (although they will cause no 
harm) since the assembler is able to check the label for itself. The assembler can also 
handle zero page labels automatically if they are defined locally within the subroutine 

via EQU. 

No more than one unresolved label can appear in a single expression. Any label not 
defined with an EQU or GEQU is unresolved at assembly time. An exception Is when 
two local labels are subtracted. 

The program counter symbol * 

The asterisk (*) may be used as a special label to stand for the current value of the 
location counter. It is syntactically equivalent to an absolute operand, and Is resolved at 
link edit time. Since It is an unresolved label, no other unresolved label may appear In an 
expression which includes the asterisk. 


Decimal Numbers 

Base ten integer numbers must be Inthe range-32768to65535. The numbertermlnates 
with the first non-numeric character. Embedded blanks are not allowed. 

Note that numbers greater than 32767 have a one in the most significant bit position. 
Signed arithmetic operations consider all numbers with the most significant bit set to be 
negative. For this reason, it is a good idea to consider the range as -32768 to 32767 for ail 
math operations. 

Because of the dual interpretation of numbers with the high bit set either as negative 
numbers or as positive numbers greater than 32767, add and subtract operations in the 
operand never result In numeric errors from overflows. Thus, 

64000+2000=66000 

would normally be considered an overflow, since 65535 is the largest positive integer. 
But this could be interpreted just as easily as 

-1636+3000=464 

which is a valid operation. 

The following are valid decimal numbers: 

1 

-1 

32000 

-32700 

64000 
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The following are invalid decimal numbers. The reason the number is invalid is stated to 
the right of the number. 


-32 000 
-33000 
66000 
3.14 


the number has an embedded blank 
-32767 is the smallest valid number 
65535 is the largest number allowed 
real numbers are not allowed 


Hexadecimal Numbers 

Hexadecimal numbers are coded with a “$” character In the first position, followed by 
zero to four hexadecimal digits. A hexadecimal digit is a numeric character or a letter 
from A to F. The number terminates with the first non-hexadecimal character. 

The following numbers are all valid hexadecimal constants. Their decimal equivalents 
are shown on the right. 

$ 0 

$0 0 

$FFFF -1 or 65535 

$89AB -30293 or 35243 

-$4 -4 or 65532 

The following are Invalid hexadecimal numbers, for the reasons indicated. 

$DEFG G is not a hexadecimal digit 

$12345 the number has more than 4 digits 

$12 34 the number has embedded blanks 

FFFF the number is not preceded by a $ character 

Octal Numbers 

Octal numbers are coded with an at sign ( @ ) followed by any number of octal digits. 
The octal digits are 0-7. Only the last sixteen bits are used. 

The following examples are valid octal constants. The hexadecimal value they 
represent is shown to the right of the octal constant. 

@ $0 

@7 $7 

@777777 $FFFF 

@7070707 $71C7 

The following are invalid octal constants: 

@8 8 is not an octal digit 

@77 77 the number contains embedded blanks 
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Binary Numbers 

The number begins with a character, followed by any number of binary digits. The 
binary digits arezero and one. The number terminates with the first non-binary number. 
Only the last sixteen bits are used. 

The following are valid binary constants. The equivalent hexadecimal number Is shown 
In the second column. 

% $0 

%01010101 $0056 

~%1 $FFFF 

%10101010101010101 $5555 

These are invalid binary constants, for the reasons indicated. 

%Z Z is not a binary digit 

%1 1 the number has embedded blanks 

Character Constants 

A character constant is one or more characters enclosed in single quote marks (’). If 
only one character is coded, the high byte is settozero. If more than two characters are 
coded, only the first two are used. If a single quote is desired, two single quotes must be 
coded. The value of a character is the equivalent ASCII code with the high-order bit set 
to one. (Unless the MSB directive is used.) 

The following examples of character constants give the hexadecimal value they 
represent in the second column. 

'A' $00C1 

" '' $00AC 

'1'" $B1AC 

' ' $00A0 

'ABC' $C1C3 

The following are Invalid character constants. 

' ' ' no closing ' 

A not enclosed in ' characters 

Arithmetic and Logicai Operations 

Any number may be preceded by a + or so long as this does not place two arithmetic 
operators (+, *, /) In a row. Add, subtract, multiply and divide operations may also be 

performed. They are written in algebraic format. A sequence of constants and 
arithmetic operators is referred to as an arithmetic expression, or simply as an 
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expression. Multiply and divide operations cannot be made with an unresolved label as 
an operand. 

Arithmetic expressions may be used as operands in logical expressions. A logical 
expression Is made up of one or more logical phrases separated by logical operators. 
The logical operators are .AND., .OR., .EOR. and .NOT. The first three combine two 
logical phrases Into a single logical value. The last reverses the value of a logical value. 



AND 

OR 

EOR 

0 0 

0 

0 

0 

0 1 

0 

1 

1 

1 0 

0 

1 

1 

1 1 

1 

1 

0 


A logical phrase takes the value TRUE or FALSE. TRUE is any arithmetic value other 
than zero, while FALSE is zero. If the logical phrase Is the result of a comparison, a 
TRUE value will always be represented as a one. Two arithmetic values may be 
compared to yield a single logical value by separating them with a comparison symbol. 
The comparison symbols and their meanings are listed below: 


= equal to 

<> not equal to 

>< not equal to 

< less than 

<= less than or equal to 

> greater than 

>= greater than or equal to 


Parentheses may be used to modify the order in which operations are performed. There 
is no fixed limit to the number of levels of parentheses that can be evaluated; if an 
expression becomes to complex, an error message will result. It is safe to assume that 
four to five levels of parentheses may be evaluated. An absolute or zero page operand 
cannot start with a parentheses, since the assembler would confuse the parentheses 
with the Indirect addressing mode. Place a + character before the left parentheses to 
avoid this. 

Resolution of operations proceeds in the following order: 

1 Resolve expressions in parenthesis 

2 Perform two byte signed Integer multiplies and divides, proceeding from left 
to right 

3 Perform additions and subtractions 

4 Evaluate logical comparisons 

5 Perform logical NOT functions 

6 Evaluate logical ANDs 

7 Evaluate logical ORs and EORs, proceeding from left to right 
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The following expressions demonstrate the rules outlined above. The value of the 
expression is shown at the right. 


-1 

$FFFF 

2*(3+$5) 

$0010 

+(4+|5)/2 

$0004 

2*(3+4*(5+6)) 

$006E 

1=2 

$0000 

1=3/2 

$0001 

1=2.0R.4<6 

$0001 

1=2.AND.4<6 

$0000 

•NOT.(l.AND.O) 

$0001 


-1 or 65636 

16 

4 

94 

0 

1 

1 

0 

1 


FALSE 

TRUE 

TRUE 

FALSE 

TRUE 


Invalid expressions are illustrated below. 


(3+$6)/2 

4*(2+3 

4*-6 


the expression starts with a ( 

mis-matched parenthese 

two arithmetic operators in a row 


Continuation Lines 

An operand may be split after any comma, parenthese, or arithmetic operator. If the 
assembler encounters a blank following such a character. It checks column one of the 
next line for a greater than sign (>). If It finds one, processing continues at the first non¬ 
blank character following the greater than sign. 

The following Is a valid continuation line. 

LDA ZP, COMENTS ARE STILL 
> X ALLOWED 

The Comment Field 

In-line comments can start In any column past the first space after the operand field. If 
an Instruction does not require an operand field, they can start in any column after the 
first space past the operation. Comments generally start In column twenty-one. A tab 
stop Is provided in that column for easy movement. 






Chapter Four 
The Assembler 

Section Three 
Assembler Directives 

Introduction 


An instruction is a line that tells the assembler how to build a machine language 
command for the microprocessor. An assembler directive tells the assembler itself to 
take some action. In some cases, this may involve reserving memory or setting up data 
tables for use by the program. Conditional assembly directives tell the assembler how to 
modify lines of source code, and what order to process them In. Other directives define 
the beginning and end of subroutines, assign values to labels, and perform various 
housekeeping functions. 

Conditional assembly directives and the macro language are covered In the next 
section. 


The Essential Directives 


It Is possible to get by using only fourteen of the assembler directives. This section 
begins by describing the features of these essential directives. They are divided into 
functional groups. 


START 

END 


start subroutine 
end program segment 
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ENTRY 

define entry point 

DATA 

start data area 

USING 

using data area 

KEEP 

keep output file 

APEND 

append a source file 

MCOPY 

copy macro file 

ORG 

set origin 

EQU 

define symbolic constant 

GEQU 

define global symbolic constant 

DC 

declare constant 

DS 

define storage 

PRNT 

send output to the printer 


The first group of directives examined here are used to divide the program into 
functional blocks. These are loosely termed subroutines, but, speaking more precisely, 
are called program segments. 

Consider the case where subroutines are not separated. All labels could be referenced 
anywhere in a program. What happens when a line is added to a large program, and the 
programmer can’t remember if the label LOOP38 has been used before? Dividing the 
program into subroutines gives the capability to define both local and global labels. 
Local labels are valid only in the subroutinethat defined them.Thus,eachsubroutinein 
a program can use the label LOOP without any problem. If a label is being added to a 
subroutine, only that subroutine need be checked to see If the label name has been used 
before. Global labels are declared explicitly as such and are valid throughout the 
program, allowing access to globally defined subroutines and data from any 
subroutine. 

From the above discussion, it is obvious that one of the first things that must be learned 
is how to define a subroutine. Using the ORCA/M assembler, both the main program, 
(that is, the entry point, which Is the first routine in a program), and every subroutine in 
the program, must begin with a START directive and terminate with an END directive. 

The use of the term “subroutine” In the sense of a program segement, which has just 
been defined as as a local range delimited by a START and an END directive, implies 
certain assumptions about programming style - namely, that it is desirable to define 
each subroutine as aseparate moduleto improve the structure of a program. A program 
may be written as one large segment, or conversely have Internal JSR assembly 
Instructions between a START and an END directive. The use of the term “subroutine” 
to describe the program segement defined between a START and END statement 
encourages the programmer to code in a more structured way. 

The START statement must have a label. This label becomes the name of the 
subroutine, and is global. Any labels defined within the subroutine Itself are a local 
labels. For example, in the following program, PROG and SUB1 are valid global labels. 
LOC1 is a local label in each subroutine. LOC2 is a local label In the main program. The 
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local labels are not valid in any subroutine other than the one that defined them. 


PROG 

LOCI 

START 

LDA 

JSR 

#3 

SUB SUBl is global 

L0C2 

BRK 

END 

L0C2 is not defined for 

the subroutine SUBl 

SUBl 

START 

ORA 

#«B0 

LOCI 

LDY 

LDA 

#0 

$300,Y 


RTS 

END 


Be sure to notice that the main program, (the first or calling program), like all 
subroutines, must also begin with a START statement and close with an END statement. 


So far, the definition of local labels has been explained; they are simply any label 
defined between a START and END statement. The label defined by the START 
statement is global, and can be accessed from any subroutine. What if a global label is 
needed Inside a subroutine - for example, to define a secondary entry point to the 
routine? This is accomplished using the ENTRY directive. The label in the label field of 
the ENTRY directive is global, just like the label In the label field of the START 
statement. Like START and END, the ENTRY directive does not take an operand. 

In addition to the subroutine, there is another kind of program segment. It is called a 
data segment. It is similar to a subroutine, but starts instead with a DATA directive and 
ends with the familiar END. The label field of the DATA directive defines the name of the 
data segment, and is global. The DATA directive uses no operand. 

As the name implies, the data segment is used to define data areas. This is a special 
program segment which Is used only for defining data; instructions are not permitted. 
For example, a JSR Instruction Inside of a data segment generates an error at assembly 
time. Labels defined in a data segment are local to the segment, but they can also be 
made local to any subroutine that needsthem. Thesubroutine using them must include 
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a USING directive somewhere in the subroutine, allowing it to access all local labels 
defined in the data segment. The following program fragment illustrates this: 

PROG START 

USING COMMON 

LDA LOCI LOCI is now a local label 


END 

COMMON DATA 

LOCI DS 6 
END 

LOCI is local to the data segment COMMON, but becomes a local label to the 
subroutine PROG because of the USING directive. (The DS directive used in the DATA 
area defines five bytes of empty storage.) 

Labels are generally defined by placing them In the label field of an instruction or 
directive, where they will automatically be assigned a value by the assembler. This value 
is the location in memory where the next Instruction will be placed. It Is also useful to be 
able to assign a value to a label manually, defining a constant or assigning a name to an 
easily forgotten fixed memory location. This is done using the equate directive, EQU. Its 
label field contains the name of the label to be defined, and the operand field contains 
the value to be assigned to the label. Global labels are defined with GEQU (global 
equate) instead. For example: 


LINE 

EQU 

$200 

TRUE 

EQU 

1 

FALSE 

EQU 

0 

RETURN 

GEQU 

$8D 

ZP 

GEQU 

$10 


Equate directives are therefore used to define constants. If the expression in the 
operand field cannot be evaluated and resolved into a value immediately, this may result 
in problems later. It is a good habit to place all local equates at the beginning of a 
subroutine, and all global equates at the beginning of a program. A label should be 
defined before use, and in fact, zero page labels must be defined before use. Zero page 
labels that will be used in more than one subroutineshould always be defined using the 
GEQU directive. The EQU directive may be used in a data segment, but normally Is used 
only for labels or constants larger than $FF. 

The next set of directives allow space to be set aside for variable storage. The first of 
these directives was mentioned In the example on data segments; It is the DS directive. 
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DS stands for define storage. The label field can contain a label, but does not need to. 
The operand Is in the form of an absolute address. Note that this doesn’t mean It has to 
be a label, just that some two byte value should result from evaluating the operand. The 
assembler will leave that many bytes of empty space in the final program. This empty 
space Is generally initialized to hex $00’s, but not in all cases. If this space is at the end of 
the entire program, the assembler simply records the values of any labels defined in the 
label field. Disk space is not wasted to put in all of the zeros for the space defined. 

In the following example, each of the DS directives reserves $24 bytes. 


ADDR 

EQU 

$240 

LABI 

DS 

$24 


DS 

ADDR/$10 

LAB2 

DS 

12*2 


Up to $FFFF bytes may be reserved with a single DS statement. 

To specify initial values that are to be stored in the space the DC directive is used. DC is 
quite versatile; with it, addresses; one, two or four byte integers; single or double 
precision floating point numbers; or hexadecimal, binary or character constants may be 
defined. The different operands needed to define the wide variety of constants available 
are explained starting on page 70. 

Up to now, the directives for telling the assembler how to create a program have been 
covered. There is another class of directives for operations such as telling the 
assembler where to store the resulting object code. This is done viathe KEEP directive. 
When used, the KEEP directive should always be the very first line of a program. The 
KEEP directive has no label. Its operand is a disk file name, optionally followed by a 
comma, a V, and the volume number of the disk that the program is to be saved onto. If 
the file name has spaces in it, it must be enclosed within single quote marks. For 
example, to save the output under the name MYPROG, and place this on disk 
volume 34, use the statement: 


KEEP ‘MYPROG’,V34 

When the assembler Is called by using a command such as ASML, the source file in 
memory is assembled. Since a single source file can only hold about 300 to 400 fully 
commented lines of code, there needsto beaa way totell theassemblerto load another 
file. This Is done with the APEND directive. The operand for the APEND directive has 
the same format as KEEP. It gives the name of the next file to be assembled. All lines In 
the original file that occur after an APEND directiveare ignored, sothe APEND directive 
should be the last line in a file. The next file need not be on the same disk as the file that 
contains the APEND directive, and in fact, the disk that has the new file doesn’t even 
need to be on-line when the assembler starts. The assembler will ask for the disk by 
volume number when it Is needed. There is no limit to the number of files that can be 
appended In this way. 
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The last directive that uses a disk file in the operand field is the MCOPY directive. It Is 
used to tell the assembler which macro libraries to search for unrecognized operation 
codes. No more than eight MCOPY statements may be active within a single program at 
any one time. The Style Manual contains guidelines on how to manage macro libraries. 

Unless it is told otherwise, the assembler, and subsequently the linker, places a 
program at memory location $800. To have it start somewhere else, the ORG directive is 
used. The operand field of the ORG directive contains the address where the next line of 
code will be placed in memory. Normally, only one ORG directive is used in a program, 
and it should be placed Immediately after the first START directive. 

The last of the basic directives Is used to send the listing produced by the assembler to a 
printer. It should be used before the first statement that Is to be printed. (It is alright to 
use It before the KEEP statement, since it doesn’t do anything to the object modules that 
the assembler creates.) The format Is: 


PRNT ON 

Having explained the PRNT directive, this concludes the introduction to the basic 
assembler directives. There are many more of them, but they may be left until these are 
mastered. At this point, however, it will be neccessary torefertothe sub-section on DC 
Value Types on page 70 to use the DC directive effectively. 


Assembler Directives 


Except for the operand field, an assembler directive is coded in the same way as an 
instruction. The operand field is used to tell the assembler directive what to do. Since 
there are a variety of assembler directives, there are a variety of types of operands. The 
format of the operand is described with the directive. 

The following descriptions of assembler directives are divided into groups having 
similar types of operands. 

Program Control Directives 

Program control assembler directives are used to define subroutines, data areas, and to 
set alternate entry points. Except for the USING statement, no operand field Is 
necessary. 

START - Start Subroutine 

Each program segement (that Is, both main programs and subroutines), must begin 
with a START statement. Labels defined inside a program segment are local labels, and 
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are valid only inside the program segment that defined them. There is nothing wrong, 
for example, with having a local label called LOOP In every program segment In a 
source file. 

Every START statement must have a label. This becomes a global label. Therefore, 
every program segment in the program Is able to reference that subroutine, allowing it 
to be called or jumped to from any program segment (Including itself). 

The label on the START statement becomes the subroutine name in the object module 
that Is the output of the assembler. Since it Is a global lablel, the link editor can inform 
other subroutines of Its location at link edit time. This allows subroutines that are 
assembled separately to be combined later by the link editor. 

END - End Program Segment 

The END directive is the last statement In a program segment or data area. It directs the 
assembler to print the local symbol table and delete the local labels from the symbol 
table. 

DATA - Define Data Area 

The DATA directive is used Instead of the START statement to define a special form of 
program segment which contains no instructions. Its purpose is to set up data tables 
which several subroutines can access. Its labels become local labels for any subroutine 
which Issues a USING statement for the data segment. The name of the data segment is 
the label field of the DATA statement, and Is global. No more than eight data segments 
may be defined in any one program. 

ENTRY - Define Entry Point 

It may be desirable to enter a subroutine someplace other than the top of the 
subroutine. Use of the ENTRY statement allows a global label to be defined for that 
purpose. The label field of the ENTRY statement becomes a global label. 

USING - Using Data Area 

This statement should appear in any program segment that wants access to a given data 
area. The operand field contains the name of the data area. Labels defined within the 
subroutine take precedence over labels by the same name in data areas. 

Space Allocation Directives 

These assembler directives are used to leave empty space and to initialize memory with 
a given value. For those which simply leave empty space, the area is filled with zeros, 
unless the area Is past all instructions and DC statements contained in a subroutine. In 
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that case, the labels generated are valid, but the memory area mapped is not actually 
saved by the assembler. This allows object modules to take up less space on the disk. 
The link editor will generate zeros for all reserved space in the final load module that it 
creates, except for space reserved at the end of the last subroutine. This space Is again 
left off to save disk space. 

DS - Declare Storage 

This directive is used to reserve sections of memory for program use. The operand Is 
coded the same way as an absolute address for an instruction. The operand is resolved 
Into a two byte unsigned integer, and that many bytes of memory are reserved. 

MEM - Reserve Memory 

The operand for this directive is two absolute addresses, separated by commas. The 
absolute addresses specify a range of memory that Is to be reserved as a data area. The 
link editor will insure that subroutines are not placed in this range of memory. This is 
done by checking the length of each subroutine to see if it will enter a reserved area. If it 
does. It is started after the end of the reserved area. This directive is intended for use 
when the high resolution graphics pages are needed. 

DC - Declare Constant 

The DC directive is used for every type of constant definition. The operand begins with 
an optional repeat count, which must be In the range 1 to 255 decimal. The variable 
being defined will be placed in the object file as many times as specified by the repeat 
count. Next comes an identifier describing the value type. This is followed by the value 
Itself, enclosed in single quote marks. The entire sequence can then be followed by a 
comma and another definition. For example, 

LABEL DC 

would place five integers into memory, four sixteen-bit and one eight-bit. The resulting 
hexadecimal values would be 

02 00 03 00 02 00 03 00 04 

The combined length of all values defined by a single DC statement cannot exceed 256 
bytes. No combination of DC statements on a single line can reference more than six 
unresolved labels. 

DC Value Types 

I - Integer 

Each number is resolved Into a two-byte signed Integer, stored with the low-order 
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byte first. (This is the order normally used by both math routines and the 6502 itself 
when making addresses references.) Multiple numbers may be coded if separated by 
commas. Each number Itself should follow the coding rulesforan absolute operand. 
Note that In the example, the division of ABS by 100 is valid only if ABS is defined 
using an EQU or GEQU directive. 


Code 


Value 


ABS 

EQU $7000 



DC 

I’438,-26,$FFFF,5/2’ 

B6 01 

E6 FF FF FF 02 00 

DC 

I’ABS,ABS/100’ 

00 70 

IE 01 


11 - One Byte Integer 

This is the same as I, except that the size of the number is one byte. The II can be 
followed by < or > to select the low or high order bytes of sixteen bit values. 

Code Value 

DC II *3, -3*, Il<’$300* 03 FD 03 

14 - Four Byte Integer 

Each Integer Is a signed number betyveen -2147483647 and 4294967296 (-2E31 and 
2E31-1). It must contain only the leading sign and decimal digits. Embedded blanks 
are not allowed. The number is resolved as a four-byte signed hexadecimal number 
and stored least significant byte to most significant byte. Multiple numbers are 
allowed If separated by commas. 

Code Value 

DC 14*1,-1,400000’ 01 00 00 00 FF FF FF FF 

80 lA 06 00 


A - Address 

This is actually the same as I, but is more mnemonic for the intended use of building 
tables of addresses. 

R - Reference an Address 

This generates a reference to an address In the object module without saving the 
address in the final program. This allows a program to note that a subroutine will be 
needed from the subroutine library without reserving storage for the subroutine 
address. In conjunction with S below, this allows for the development of a p-system 
which loads and links only those parts of the p-system language needed by a 
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particular program. This option is then used by thep-code instructions to insurethat 
any library subroutines that will be needed to execute that instruction are linked. 

Note that this directive does not save anything in memory. Even though it doesn’t 
save anything, it still counts as two bytes per label against the 256 bytes allowed in a 
single line. 

S - Soft Reference 

This generates two bytes of storage for each address in the operand, but does not 
instruct the link editor to linkthesubroutines intothe final program. If thesubroutine 
is not linked, the binary program produced by the link editor will have $0000 as the 
two byte address. This allows a table of addresses to be built, but only those 
subroutines requested elsewhere In the program (usually by an R type reference) 
have their addresses placed in the table. See the discussion of R, above. 

H - Hexadecimal Constant 

The string between the single quote marks may contain any sequence of 
hexadecimal digits (0-9 and A-F) and blanks. Embedded blanks are removed, and 
the hexadecimal value Is stored unchanged. If there are an odd number of digits, the 
last byte is padded on the right with a zero. 

Code Value 

DC H»01234ABCDEF» 01 23 4A BC DE FO 

DC H’llll 2222 3333’ 11 11 22 22 33 33 

B - Binary Constant 

The string between the single quote marks can contain any sequence of zeroes, 
ones, and blanks. The blanks are removed, and the resulting bit values are stored. Ifa 
byte is left partially filled. It is padded on the right with zeros: 


Code Value 

DC B’Ol 01 01 10’ 66 

DC B’lllllllll’ FF 80 

C - Character String 

The string enclosed in single quote marks may contain any sequence of keyboard 
characters. If a single quote mark Is desired, enter it twice to distinguish It from the 
end of the string: 

Code Value 

DC C’NOW IS THE TIME . . . ’ CE CF D7 AO C9 D3 AO D4 
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C8 C6 AO D4 C9 CD C5 AO 
AE AE AE 

DC C^NOW^’S THE TIME’ CE CF D7 A7 D3 AO D4 C8 

C6 AO D4 C9 CD C5 

Normally, strings are stored with the high-order bit set, allowing them to be 
displayed directly on the Apple II screen. It may be equally desirabletogeneratetrue 
ASCII characters. These are obtained by directing the assembler to turn off the most 
significant bit using the MSB directive, which is described later on in this section. 

F - Floating Point 

Numbers are entered as signed floating point numbers, with an optional signed 
exponent starting with E. Embedded blanks are allowed anywhere except within a 
sequence of digits. 

The number is stored as a five byte floating point number. Byte one contains the 
signed exponent plus $80. The exponent Is In base two. Bit one of the four-byte 
mantissa Is the sign bit, and is zero for positive numbers. The implied location of the 
decimal point is before the first byte of the mantissa. The mantissa is left justified, 
(normalized) so that the most significant bit will always be one; this allows the sign 
bit to be stored there without conflict. The mantissa is stored most significant byte to 
least significant byte. This format is compatible with Applesoft routines and the 
included floating point subroutine package. 

Numbers can range from approximately 1E-38 to 1E+38. The mantissa is accurate to 
over nine decimal digits: 

Code 

DC F’3,-3,.36El,6.a5 E-2’ 


D - Double Precision Floating Point 

This Is identical to F, except that a ten-byte number is generated with a two-byte 
exponent and an eight-byte mantissa. Numbers can range from about 1E-9864 to 
1E+9864. The mantissa is accurate to slightly more than 19 decimal digits. The 
exponent is stored most significant byte first: 

Code Value 

DC D’3,-3,.36E1,6.25 E-2’ 8002 40000000 00000000 

8002 COOOOOOO 00000000 
8002 60000000 00000000 
7FFD 00000000 00000000 


Value 

82 40000000 
82 COOOOOOO 
82 60000000 
7D 00000000 
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PAGE - Skip to Page Boundary 

This functions as a variable length DS statement. It is used to guarantee that the next 
instruction or data declaration starts on a page boundary, filling memory with zeros 
until such a boundary is reached. This is sometimes desirable when programming for 
maximum speed. 

Note that the results of a page directive will not appear In the assembled listing. It is not 
until the link editor decides where the subroutine will be placedthattheeffectof a page 
directive can be determined. 

ORG - Origin 

When the assembly process starts, the assembler assumes that the program will be 
located at $800. The ORG statement can be used to change that default and start the 
program at some other location. The location is specified as an absolute address In the 
operand field. This directive must only appear inside a program segment. 

The ORG statement can be used after the first instruction or data definition, but it 
functions a little differently. If the address specified in the operand field is past the 
current location counter, enough zero bytes are generated to reach the specified 
address. References to an address before the current location counter are not allowed. 

As with the PAGE directive, the effect of an ORG cannot be determined until the link 
editor decides where to put the subroutine containing it. ORG has no effect on the 
output listing of the assembler. 

EJECT - Eject the Page 

When a printer is In use, this directive causes the output to skip to the top of the next 
page. This can be of help in structuring the output of long subroutines. The directive 
does not effect the code sent to the output file in any way. 

TITLE - Print Header 

The title directive has an optional operand. If coded. It must be a legal string, and must 
be enclosed in single quote marks if It contains blanks or starts with a single quote mark. 
If the string is longer than sixty characters. It is truncated to sixty characters. 

If the TITLE directive Is used, page numbers will be placed at the top of each page sent 
to the printer. If an operand was coded, the string used will be printed atthetop of each 
page. Immediately after the page number. 

Immediate Operand Directives 

The following assembler directives all use the same type of operand. It is coded exactly 
like an absolute address. 
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MERR - Maximum Error Level 

MERR sets the maximum error level that can be tolerated and still allow the assembled 
program to link edit immediately after the assembly (as would happen with a RUN 
command from the monitor). The default value Is zero. The operand is evaluated to a 
one byte positive integer. 

EQU - Equate 

The label is assigned the value of the operand instead of the location counter. This 
allows a name to be assigned to a numeric value, and used instead of the number in 
further operands. 

Although the operand may contain labels, these labels must already have a value. If they 
do not, an error Is generated. This is because the resulting value may be a zero page 
address. During the first pass, the assembler has no way of knowing this, since It could 
not resolve the equate. Instructions are assumed to be absolute addresses on the first 
pass, and two bytes are reserved. On the second pass, the equate would be resolved as 
zero page. The addresses would now occupy only one byte, and further addressing 
would be Incorrect. 

For the same reason, it is important that equates defining zero page addresses be 
defined before they are used. 

GEQU - Global Equate 

This is Identical to the EQU directive, except that the label is saved in the global symbol 
table. All program segments are then able to use the label. This Is the recommended 
way to define zero page equates. 

FPLEN - Floating Point Length 

Only two values are valid for the operand In this directive, 4 and 5. The default is 5. The 
number defines the length in bytes of floating point numbers, which are normally five 
bytes long to be compatible with Applesoft BASIC. The length may be set to four, to be 
compatible with other high level languages. The four byte number is computed 
normally internally, then truncated to four bytes before storing. 

The directive changes the length of double precision numbers in a similar manner; 
double precision numbers are always twice as long as single precision floating point 
numbers. 

DOS Control Directives 

All DOS control directives specify a disk file name in the operand. Any valid DOS file 
name may be coded. If the file name has embedded blanks or commas. It must be 
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enclosed in single quote marks, and enclosed single quote marks must be doubled. An 
optional volume number can be coded after the name, as in the example. 

LABEL COPY 'DISK''SPILE 0NE',V38 

If the volume number is not coded, it is assumed to be the volume number of the last disk 
accessed. 

APEND - Append a File 

Processing is transferred to the beginning of the specified file. Any lines following the 
APEND directive in the original file are ignored. 

COPY - Copy a File 

Processing is transferred to the beginning of the specified file. After the entire file Is 
processed, assembly continues with the first line after the COPY directive In the original 
file. A copied file can copy another file, up to four levels deep. 

KEEP - Keep Object Module 

The assembled code Is saved on disk as a relocatable object module, using the specified 
name as the root name. The link editor may then be used to generate an executable 
binary file. 

MCOPY - Copy Macro Library 

The name of the file is placed In a list of available macro libraries. If an operation code 
cannot be identified, all macro files in the list are loaded into the macro buffer in 
sequence, and checked for a macro with the specified name. The search begins with the 
macro file in memory, proceeds to the first file in the list of macro files, and continues 
through to the last file In the list, in the order the respective MCOPY statements were 
encountered (skipping the one that was originally in memory). If no macro with a 
corresponding name is found, an error is generated. 

No more than eight macro libraries can be active at any one time. Macro libraries cannot 
contain COPY or APEND statements. 

MDROP - Drop a Macro Library 

Removes the specified library from the list of macro libraries. This might be necessary if 
more than eight libraries are being used. It can also speed up processing if the library Is 
no longer needed. 

If the macro library is in memory at the time the MDROP statement is encountered. It Is 
left there and searched for macros until a search is made which loads a different library. 
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or until an MLOAD directive is used. 

MLOAD - Load a Macro Library 

The list of macro libraries is checked. If the specified file Is not In the list, it is placed 
there. The file is then loaded into the macro library buffer. 

This directive can be used to speed up assemblies by helping the macro processor to 
find macros. 


Control Directives 

The directives In this section are used to set flags that control the assembly process. 
The operand for each of the directives consists of either ON or OFF, choosing whether 
or not the option Is In effect. The default setting Is shown in the definition line. 

LIST ON - List Output 

A listing of the assembler output is sent to the current output device. If the listing Is 
turned off, the assembly process speeds up by about 10%. 

SYMBL ON - Print Symbol Tables 

An alphabetized listing of all local symbols Is printed following each END statement. 
After all processing is complete, global symbols are printed. If this option is turned off, 
assemblies speed up slightly. The option can also be used to save paper. 

ERROR ON - Print Errors 

If LIST ON ha5 been specified, errors are always printed, regardless of this flag. If LIST 
OFF has been specified, this flag allows error lines to still be printed. If turned off, errors 
are no longer printed, but the number of errors found will still be listed at the end of the 
assembly. 

GEN OFF - Generate Macro Expansions 

If GEN Is turned on, all lines generated by macro expansions are shown on the output 
listing. Each line generated by a macro has a + character to the left of the line. If GEN is 
turned off, only the macro definition is printed In the assembly listing. Errors within the 
macro expansion are still printed, along with the line causing the error. 

EXPND OFF - Expand DC Statements 

If turned on, this option causes all bytes generated by DC statements to be shown In the 
output listing. Since only three bytes of a DC statement can be displayed on a line, the 
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option defaults to OFF to save paper and patience. When the option is turned off, only 
the first three bytes of the generated code are shown with the output. 

PRNT OFF - Send Output to Printer 

If PRNT ON is coded, output is sent to the printer. A printer capable of printing at least 
eighty columns Is expected there. If a printer Is not connected, the system will hang. The 
slot number and printer characteristics may be changed by re-configuring the 
operating system. If the option Is turned off, output is sent to the video display. 

MSB ON - Set the Most Significant Bit of Characters 

Character constants and characters generated by DC statements have bit seven set, 
and so will appear normal when sent to the Apple screen. If MSB OFF Is coded, 
characters generated have bit seven turned off, and appear normal to ASCII devices. 




Chapter Four 
The Assembler 

Section Four 
Macro Language 

and Conditional Assembly Directives 

Introduction to Macros 


This chapter describes how to create user-defined macros. It is not neccessary to be 
able to write a macro in order to use one; chapter six describes how to use the macros 
supplied in the macro library. It is therefore not neccessary to know the material in this 
section in order to use the assembler; the macro language is an advanced capability, 
which should be studied after the fundamental features of the assembler have been 
mastered. 

A macro is simply a statement of the same form as an instruction which tells the 
assembler to generate other Instructions. The usefulness of a macro ranges from 
something as simple as assigning an instruction name to an easily forgotten subroutine 
address, to something as complex as generating a sequence of instructions for a math 
or I/O operation. It is possible to create an entirely new instruction set using macros. 

The Macro File 

A new macro is created by coding a macro definition, which tells the assembler which 
instructions to replace the macro ca//with. These definitions are kept in a special file 
called a macro file. Macro files are created using the text editor In the same way that a 
source file is created. The distinction between the two is in the way the assembler 
handles them. Macro files are Included In the source stream using MLOAD and MCOPY 
commands. The assembler loads them into a special area of memory called the macro 
buffer as they are needed. When an unidentified operation code is encountered in the 
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source file, the assembler searches for a macro definition by that name in the macro 
buffer. 


Macro Language Directives 


There are four macro language directives: MACRO, MEND, MEXIT, and MNOTE. With 
the exception of MNOTE, these directives are valid only in a macro file; if used inside of 
a regular source file, they will create an error. 

The MACRO and MEND Directives 

Each macro definition begins with a MACRO directive and ends with an MEND 
directive. These directives are coded like an operation code. No operand or label Is 
needed, and any present is ignored. Their sole purpose is to set the macro definition 
apart from others In the file. Their use will become clear in the examples that follow 
shortly. 

MNOTE - Macro Note 

A macro definition may include an MNOTE statement. The operand of an MNOTE 
statement contains a message, optionally followed by a comma and a number. The 
assembler prints the message on the output device as a separate line. If the number is 
present, it is used as a severity code for an error. 

Assume that the following statements appear In a program: 

* MNOTE FOLLOWS 

MNOTE * ERROR! ’,4 

The output would look like this: 

lOFE * MNOTE FOLLOWS 
ERROR! 

Assuming that there were no other errors in the assembly, the maximum error level 
found (printed at the end of the assembly) would be four. 

MNOTE is designed for use when conditional assembly directives are used to scan 
paramters passed via a macro call for correct (user defined) syntax. Although MNOTE 
statements are intended for use inside macros, they are legal inside of a source 
program. 


MEXIT - Exit Macro 
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An MEXIT directive indicates that a macro expansion is complete. Unlike MEND, it does 
not indicate the end of the macro definition. A good way conceptualize this directive Is 
to think of it as a return from a macro definition. The MEND is the end of the definition, 
but the MEXIT can return from within the macro definition. The MEXIT directive Is 
designed for use with conditional assembly branches. 


Writing Macro Definitions 

The Macro Definition Statement 

Immediately following the MACRO statement is the macro definition statement. The 
name of the macro being defined is placed in the the operation code field. If the 
operation code that the assembler Is trying to identify matches it, the assembler uses 
the definition that follows to replace the macro statement in the source file with the 
instructions found in the body of the macro itself. The macro definition operation code 
may be any sequence of keyboard characters except blanks. It may contain from one to 
ten characters. 

Consider the following simple macro as an example. It Is used to print a character on the 
screen. The Apple monitor has a subroutine called COUT which does this, but it is 
inconvenient to have to always remember its address. To remedy this, a macro may be 
defined, using the same name (COUT) by entering this definition in a new source file 
called MACROS: 

MACRO 

COUT 

JSR $FDED 
MEND 

COUT may now be used as a new instruction: 


MCOPY MACROS 


LDA #*A* 
COUT 
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Following the COUT insturction, the assembler includes the macro expansion, yielding 
the sequence 


LDA 

COUT 

+ JSR $FDED 


in the output listing. The new instruction COUT may be used as many times as desired 
anywhere In a source program provided the MCOPY MACROS directive is also 
included. The assembler always prints the name of the macro (in this case COUT) to 
show how instructions that follow were generated; the JSR instruction is the only part of 
the macro expansion that actually generates code. The + character at the beginning of 
the line containing the JSR instruction Is put there by the assemblerto Indicatethatthe 
line was generated by the macro processor, rather than coded directly by the 
programmer. The lines that comprise the macro expansion are normally not printed in 
the assembly listing; a GEN ON directive must be Issued earlier in the program to list the 
macro expansion. 

The statements between the macro definition statement and the MEND statement are 
called model statements, since the macro processor uses them as models for the new 
Instructions. The Instruction In the source file that caused the macro to be expanded is 
called the macro call statement, or simply the macro call. 


Symbolic Parameters 


A symbolic parameter Is a special variable used by the assembler. Unlike labels, they are 
true variables, that Is, they may be assigned a value which can later be changed. They 
come In three kinds: A for arithmetic, B for boolean (logical) and C for character type. 

A symbolic parameter is coded as an & (ampersand) character followed by the symbolic 
parameter name. The name itself has the same syntax conventions as a label. 

When the assembler encounters a symbolic parameter, it replaces It with its value 
before assembling the line. The value may be set In several ways. One way, described 
below, Is by passing the values during the macro call. Only character type symbolic 
parameters may be passed this way; the use of the other types of symbolic paramters 
will be explained in the sub-section on conditional assembly. 
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Positional Parameters 

One way to define a character type symbolic parameter is to include it in the label or 
operand field of a macro definition statement. Symbolic parameters defined in this way 
may be said to be Implicitly defined by appearing on the macro definition line. 
Character type symbolic parameters defined In this way are used to pass actual values 
to the symbolic parameters during a macro call, as will be seen in the example below. 
Revisiting the macro defined above to output a character, a new, more powerful macro 
definition may be written which reads: 


&LAB 

MACRO 

GOUT 

&CHAR 

&LAB 

LDA 

&CHAR 


JSR 

$FDED 


MEND 



This new macro is called from a source program as follows: 



BEQ 

Ll 


GOUT 

#‘A 


JMP 

L2 

LI 

GOUT 


L2 

RTS 



At assembly time, the following code is generated. Note again that assembler includes 
the macro call statement only to show what generated the new lines; there is no 
generated code associated with the macro call line itself. 



BEQ 

Ll 


GOUT 

#‘A» 

+ 

LDA 

#‘A 

+ 

JSR 

$FDED 


JMP 

L2 

Ll 

GOUT 


+L1 

LDA 

#‘B’ 

+ 

JSR 

$FDED 

L3 

RTS 
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When used this way, &CHAR is referred to as a positional parameter. This is because it 
gets its value by being matched with a character string in the source file by position. 
This becomes clear when a macro is defined which has two or more symbolic 
paramters. Also note that the symbolic parameter defined in the label field of the of the 
macro definition (&LAB) resulted In the label field of the first line of the macro 
expansion receiving the value of L1 after the second macro call. The symbolic 
parameter &LAB was also coded In the macro definition line, where the value of the 
macro call label field was substituted for it during the macro expansion. 

The following example, which is a macro to print two characters, shows how positional 
parameters are set via the macro call: 

MACRO 

&LAB C0UT2 &C1,&C2 

LDA &C1 
JSR $FDED 
LDA &C2 
JSR $FDED 
MEND 

Observe that the two symbolic parameter declarations on the macro definition line were 
separated by a comma, with no intervening spaces. The comma delimits the different 
positional parameters; spaces are not allowed. When the macro Is called, as shown 
below, the actual parameters are coded identically, that is, with commas separating the 
fields, and no intervening blanks: 



C0UT2 

#‘A’ 

+ 

LDA 

#‘A’ 

+ 

JSR 

$FDED 

+ 

LDA 


+ 

JSR 

$FDED 


The macro processor determined which actual parameters to substitute for which 
symbolic paramters by matching their relative positions in the macro call statements 
with those In the macro definition. 

Once conditional assembly instructions are introduced below, it will be seen that there 
are times when a positional parameter may (optionally) not be coded. In this case, 
nothing need be coded in the source file. However, all commas must be included, as If 
something had been coded. The macro processor keeps count of the position using the 
commas, so that later positional parameters appear in the right place. 
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Keyword Parameters 

A keyword parameter is another way to reference a symbolic parameter defined in the 
operand field of a macro definition. The name of the symbolic parameter is typed, 
followed by an equal sign, and the value to assign it. For example, a call to the COUT2 
macro could be coded as 



C0UT2 

C2=#‘B 

+ 

LDA 

#‘A’ 

+ 

JSR 

$FDED 

+ 

LDA 

#‘B’ 

+ 

JSR 

$FDED 


When only keyword parameter substitution Is used, the order Is not important. The 
same rules as for positional parameters regarding commas and blanks do apply, 
however. Keyword and positional parameters can be mixed. If this is done, keyword 
parameters takes up a space, and are counted for determining positions. The macro 
processor simply counts the number of commas encountered when setting values for 
positional parameters. 

Subscripting Parameters in Macro Call Statements 

All types of symbolic parameters may be subscripted. Character type symbolic 
parameters defined in the macro definition statement are subscripted by including the 
subscripted variables In parentheses on the macro call line. For example. If a macro call 
statement contained the following phrase In the operand field: 

SUB = (ALPHA, , GAMMA) 

(an example of keyword parameter substitution), the symbolic parameter &SUB forthe 
given expansion would have three subscripts allowed. The Initial valueof each element 
would be: 

&SUB(1) ‘ALPHA’ 

&SUB(2) null string 

&SUB(3) ‘GAMMA’ 

To effectively use subscripted actual parameters, the macro Itself would have to be 
coded so as to detect the number of subscripts allowed and to take appropriate action 
via conditional assembly directives. 
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Conditional Assembly Directives 


Conditional assembly directives allow macros to assume theirfull potential. They allow 
symbolic parameters to be re-defined and new values to be assigned to them. The order 
in which statements are processed by the assembler can also be modified. 

All of the conditional assembly directives described below are also valid in source files. 
The reason they are included here Instead of In section three is that their main use Is 
inside of macro definitions. 


Explicitly Defined Symbolic Parameters 

The use of character type symbolic parameters In the macro definition and macro call 
lines was explained above. 

In addition to being defined implicitly in the macro definition statement as in the case of 
character-type symbolic parameters, all symbolic parameter types (arithmetic, 
boolean, and character) may be declared explicitly. 

Explicitly defined symbolic parameters are not set with actual parameters via a macro 
call. Rather, they are used as internal variables within a macro. Using the conditional 
directives, their values may be set and reset during the macro expansion, resulting in an 
extremely powerful conditional assembly capability. 


Explicitly defined symbolic parameters may also be subscripted. The subscript must 
follow the symbolic parameter name. Only a single subscript is allowed, which must be 
In the range from 1 to 255. A symbolic parameter used as a subscript for another 
symbolic parameter cannot be subscripted. 


In the following example, assume that four symbolic parameters have been defined, as 
listed below. The maximum allowable subscripts for the subscripted symbolic 
parameters are shown with the symbolic parameter name. Next is the type, followed by 
the value. Subscripted symbolic parameters havetheirvalues listed on successive lines. 


name 


type value(s) 


&ART A 

&BIN(2) B 

&CHAR C 

&CHAR2(3) C 


$FE 

1 (true) 

0 (false) 

‘LABEL » 

‘STRINGl* 

* * (null string) 


Below are instructions as typed in a source file, on the left, with the instructions as 
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expanded by the assembler on the right. 


&CHAR 

LDA 

&CHAR2(1) 

LABEL 

LDA 

STRINGl 


STA 

&CHAR.&BIN(2) 


STA 

LABELO 


LDA 

#&ART 


LDA 

#254 


BEQ 

L&BIN 


BEQ 

LI 


LDA 

LB&CHAR2(2) 


LDA 

LB 

L&BIN(1) 

STA 

EQ&BIN(2) 

LI 

STA 

EQO 


LD&CHAR2(3) #1 


LDA 

#1 


Note that a boolean symbolic parameter becomes zero if false and one if true. The null 
string is valid; it is replaced by nothing. 

The second line demonstrates the use of the period to concatenate symbolic 
parameters. The period itself does not appear in the final line. It can be used after any 
symbolic parameter, regardless of how that parameter was defined. It must be used If a 
symbolic parameter is followed by a character, or if a subscript is followed by a 
mathematical symbol or expression. 

Symbolic Parameter Definition Statements 

Symbolic parameters may be defined either for the current macro expansion or for the 
entire subroutine. Defining symbolic parameters whose scope Is the entire subroutine 
allows macros to communicate with each other. Symbolic parameters which are only 
valid inside a macro are called local symbolic parameters; those valid throughout the 
subroutine are called global symbolic parameters. 

A symbolic parameter definition statement does not contain a label. The operand field 
consists of the name of the symbolic parameter to be defined. If the symbolic parameter 
is to be subscripted, the maximum allowable subscript must be specified In parentheses 
immediately following the symbolic parameter name. 

Symbolic parameter definition statements are not printed in the output listing unless 
they contain errors. 

The symbolic parameter definition operation codes and their meanings are listed 
below. 


Op Code 

Symollc Parameter Type 

LCLA 

local arithmetic 

LCLB 

local boolean 

LCLC 

local character 

GBLA 

global arithmetic 

GBLB 

global boolean 

GBLC 

global character 
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A permanent global symbolic parameter called &SCNT of type arithmetic is available. 
Its value Is set to one at the beginning of each subroutine and is Incremented at the 
beginning of each macro expansion. It is used to prevent labels defined inside macros 
from being duplicated If the same macro Is used morethan once Inthesamesubroutine. 
This is done by concatenating &SCNT to any labels used within the macro definition 
itself. 


Set Symbols 

Symbolic parameters are set and modified using set symbols. The set symbol is placed 
in the op code field, and Its type must match the type of the symbolic parameter it Is to 
set. The symbolic parameter being set appears In the label field, followed by an optional 
subscript. The operand field contains the new value to be assigned to the symbolic 
parameter. Expressions containing symbolic parameters may be used to set other 
symbolic parameters. 

Set symbols are not printed on the output listing unless they contain errors. 

SETA - Set Arithmetic 

The operand field is resolved as a two byte signed hexadecimal number and assigned to 
the symbolic parameter in the label field. 

SETS - Set Boolean 

The operand field contains a boolean phrase, which Is evaluated as true or false. If true, 
the symbolic parameter is assigned a value of one. If false, or If the line contains an 
error, the symbolic parameter is assigned a value of zero. 

The operand field for a SETS instruction is coded using the same rules as an absolute 
address. It is referred to as a boolean phrase because It most generally takes on a value 
of true or false (one or zero). 

Recall that section two, which described the coding rules for address fields, allowed 
boolean operators to be used in expressions. If they are used, the resulting expression 
has a boolean value that appears as a zero or one used to indicate false and true boolean 
results. Arithmetic results are also valid in a boolean expression, thus a boolean variable 
can be used In the same way as arithmetic variables. Since only one byte Is reserved for 
each boolean value, the boolean variable selects the least significant byte of an 
arithmetic result, using it as an unsigned arithmetic value in the range 0 to 255. Use of 
such a result in a boolean statement will result in the value being evaluated as true if the 
value Is non-zero, and false if the value is zero. 

SETC - Set Character 


The operand is evaluated as a character string and assigned to the symbolic parameter. 
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Several sub-strings may be concatenated to make up the final string; they are separated 
in the operand field by plus characters (+). Embedded blanks are not allowed. Literal 
strings containing blanks, commas, or plus signs must be enclosed in single quote 
marks. Single quote marks inside single quote marks must be doubled. 

AMID - Assembler Mid String 

This is a special kind of character type set symbol which provides a mid-string function. 
It has three arguments in the operand field, separated by commas. Embedded blanks 
are not allowed. 

The first argument Is the string to be operated on. It must be a simple string (no 
concatenation Is allowed). If the string contains embedded blanks or commas, it must 
be enclosed In single quote marks. Single quote marks Inside single quote marks must 
be doubled. 

The second and third arguments are of typearithmetic. The second argument specifies 
the position within the target string of the first character to be chosen. It must be greater 
than zero. Characters from the target string are numbered sequentially, starting with 
one. 

The third argument specifies the number of characters to be chosen. 

If the combination of the last two arguments result in an attempt to select characters 
after the last character of the target string, the selection is terminated. Characters 
already selected are still valid. 

The resulting string Is assigned to the character type symbolic parameter specified In 
the label field. 

instruction 

&CHAR AMID * TARGETS 2, 3 

&CHAR AMID ‘TARGETS 5,3 

&CHAR AMID ‘TARGETS 7, 3 


ASRCH - Assembler String Search 

This is aspecial form of arithmetic set symbol. It Implementsastring search function for 
character type symbolic parameters. 

The ASRCH directive has three arguments. The first is of type character, and Is the 
target string to be searched. The second is also of type character, and is the string to 
search for. The last is of type arithmetic, and Is the position In the target string to begin 
the search. The search can be conducted for any sequence of keyboard characters. 


resulting string 

ARG 

ET 

null string 
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The label field contains an arithmetic symbolic parameter. It Is set to the character 
position in the target string where the search string was first found. If the search string 
was not found, It receives the value zero. 

instruction 

&NUM ASRCH ‘TARGET’,GE,1 
&NUM ASRCH ‘TARGET SGE, 6 
&NUM ASRCH ‘TARGET *,X,1 

AINPT - Assembler Input 

The operand is optional and, if coded, consists of a literal string. If the operand is coded, 
the string contained in the operand is printed on the screen during pass one as an Input 
prompt. The assembler then waits for a line to be entered from the keyboard. The string 
entered is assigned to the character type symbolic parameter specified In the label field. 

During pass one, keyboard responses are saved by the assembler. When an AINPT 
directive is encountered on pass two, the response given in pass one is again placed In 
the symbolic parameter specified in the label field. Thus, keyboard response Is only 
needed one time for each input, but the symbolic parameter is set to the response on 
both pass one and pass two. This means that it is safe to use the response for 
conditional branching. 

Refer to the operating system source code on disk for examples of how AINPT is used. 
The printed assembler listing in this manual will not show them because the directive is 
not listed unless it contains an error. 

Branching Directives 

Branching directives alter the flow of source statements to be processed by the 
assembler. This allows the same macro (or source code) be a assembled differently 
based on a given condition. 

Sequence Symbols 

A branch must have someplace to go to. In the case of conditional assembly branches, 
this Is provided by sequence symbols. 

A sequence symbol is a line with a period in column one, followed by a label. Comments 
may follow the label after at least one space. Instructions contained in the line are 
treated as comments. The line is not printed in the output listing. 

AGO - Unconditional Branch 

The operand contains a sequence symbol. The macro definition (or subroutine, if not 


resulting value 

4 

0 

0 
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used in a macro) is searched for a matching sequence symbol. Processing continues 
with the instruction immediately following the sequence symbol. 

The search range for a source file Includes the entire file, not just the subroutine 
containing the AGO statement. Searching begins in the forward direction and 
continues until the sequence symbol Is found or the end of the file is reached. The 
search then begins with the Instruction before the AGO statement and continues 
toward the beginning of the file. 

The search process in a macro definition Is similar, except that the search will not cross 
a MEND or MACRO directive. 

Searches for sequence symbols will not cross into a copied or appended file; they are 
limited to the file in memory. 

The AGO statement is not printed in the output listing unless It contains an error. 

In the following example, the assembler encounters the Initial AGO statement. 
Processing continues at the sequence symbol. All lines between the AGO and 
sequence symbol are ignored by the assembler. 

AGO .THERE 

I THESE LINES ARE IGNORED. 


.THERE 

AIF - Conditional Branch 

The operand contains a boolean phrase followed by a comma and a sequence symbol. 
The boolean phrase is evaluated. If true, processing continues with the first statement 
following the sequence symbol; if false, processing continues with the first statement 
following the AIF statement. 

The AIF statement is not printed in the output listing unless It contains an error. 

As an example, consider a file which contains the following directives and instructions: 



LCLA 

&LOOP 

&LOOP 

SETA 

4 

.TOP 

ASL 

A 

&LOOP 

SETA 

&L00P-1 


AIF 

&L00P>0,.TOP 
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The output listing will contain these lines: 

ASL A 

ASL A 

ASL A 

ASL A 

Miscellaneous Directives 

ANOP - Assembler No Operation 

The ANOP directive does nothing. It is used to define labels without an instruction. The 
label assumes the current value of the program counter. 

ACTR - Assembly Counter 

Each time a branch Is made In a macro definition, a counter is decremented. If it reaches 
zero, processing of the macro stops. This protects the user from infinite loops. 

The ACTR instruction is coded with a number from 1 to 255 in the operand field. The 
counter Is then assigned this value. The ACTR statement is used to limit the number of 
loops caused by conditional assembly branches. In loops with morethan 255 iterations. 
It must be reset within the body of the loop to prevent the counter from reaching zero. 

The counter value is set to 255 automatically at the beginning of each macro. 

The ACTR - statement is not printed unless it contains an error. 

Attributes 

In certain cases it is desirable to know something about a label or symbolic parameter 
other than Its value. This Information is provided yia attributes, which may bethought of 
us functions that return information about a label or symbolic parameter. 

An attribute is coded as an attribute letter, a colon, and the label orsymbolic parameter 
it is to evaluate. For example, the length attribute of the label LABEL is coded as 

L: LABEL 

Attributes may be used in operands in the same way that a constant is used. 


C - Count 

The count attribute givesthe numberof subscripts allowed in a symbolic parameter. It is 
normally used to find out If a multiple argument has been assigned to a symbolic 
parameter by a macro call. It can also be used to find out If a symbolic parameter (or 
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label) was defined at all; if not, the count attribute is zero. 
The count attribute of a defined label Is one. 


L - Length 


The length attribute of a label is the number of bytes generated by the line that defined 
the label. 


The length attribute of an arithmeticsymbolic parameter Is two. Fora boolean symbolic 
parameter It is one. Fora character symbolic parameter, it isthe number of characters in 
the current string. If the symbolic parameter is subscripted, the subscript of the desired 
element should be specified; otherwise, the first element is assumed. 


T - Type 


The type attribute evaluates as a character. The type attribute of a label indicates the 
type of the operation in the line that defined the label. For a symbolic parameter, the 
type attribute Is used to distinguish between A, B and C type symbolic parameters. The 
character that is returned for each type is indicated in the table below. 


Character 


Meaning 



A 

B 

C 

D 

F 

G 

H 

I 

J 

K 

L 

M 

N 

0 

P 

R 

S 

X 

Y 

Z 


Address Type DC Directive 
Boolean Type DC Directive 
Character Type DC Directive 

Double Precision Floating Point Type DC Directive 

Floating Point Type DC Directive 

EQU or GEQU Directive 

Hexadecimal Type DC Directive 

2 Byte Integer Type DC Directive 

4 Byte Integer Type DC Directive 

Reference Address Type DC Directive 

Soft Reference Type DC Directive 

Instruction 

Assembler Directive 

ORG Directive 

PAGE Directive 

1 Byte Integer Type DC Directive 
DS Directive 

Arithmetic Symbolic Parauneter 
Boolean Symbolic Parameter 
Character Symbolic Parameter 


If a DC Statement contains more than one type of variable, the last type in the line 
determines the type attribute. 
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Final Notes 


It is worth noting that many assembler directives are not printed, yet they do have a label 
field. Generally, it is not a good idea to put labels in this field, since the line will not be 
found in the output listing. 

Examples of macro definitions and howthey use conditional assembly directives can be 
found in listing two, which contains listings of the macros In the macro library. 
Examples of how to use macros in a subroutine can be found in the subroutine library 
listing, as well as the listing of the operating system. 

Macros may contain references to other macros, up to four levels deep. They cannot 
contain COPY or APEND directives. 
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Chapter Five 
The Link Editor 


Overview 


This chapter describes the use and operation of the link editor supplied with the 
assembler. The link editor has the job of taking individual subroutines and combining 
them into a complete program. This usually means relocating certain subroutines and 
telling each subroutine where other subroutines are located. The principal advantage of 
a link editor is that if a single subroutine has an error, only that subroutine containing 
the error need be reassembled, rather than the entire source file. The link editor can 
then combine the new subroutine with the old ones to produce an executable program. 

This scheme results in three distinct kinds of files that the ORCA/M system uses. The 
first Is the source file; these files are created using the system editor. Source files are 
saved to disk with the monitor SAVE command. They have the file type S , which may be 
seen to the left of the file name when the disk is cataloged. S type files are non-standard 
files used only by the ORCA/M operating system. 

The assembler is used to convert the source file into an object module, which in turn is 
the kind of file the link editor uses. The object module has a file type of R, meaing 
relocatable, since the link editor can relocate the code contained within an object 
module. Note that the link editor does not know or care what source language produced 
the object module. A Pascal or BASIC compiler designed for use with this system could 
produce the same type of object module as the assembler. 

Cutput from the link editor is in the form of a binary file with filetype B. This file is ready 
to be executed using a BRUN command. It may be executed from standard DCS or 
directly from the monitor. 

The link editor is invoked by using any monitor command that does an assembly 
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followed by a link edit, such as ASML. it is also be invoked by using the LINK command 
with a file name. Parameters for the LINK command will be described shortly. 


The Link Edit Process 


No matter how the link editor is invoked, the process is very much the same. The link 
editor is a two pass linker. Pass one begins by locating an object module on disk and 
loading the module into memory. Subroutines are assigned final memory locations for 
the load module, and the length ofthesubroutine iscalculated. All global labelsdefined 
in the object module are assigned values and placed in a symbol table. The process Is 
then repeated with the next subroutine. 

After all subroutines have been processed in the above manner, pass two starts over 
with the first subroutine. This time, global labels referenced by the subroutine are 
looked up in the symbol table and resolved In the output file. The subroutine is then 
placed in the load module on disk. This process Is then repeated for each of the other 
subroutines. 


Object Modules Created by the Assembler 


When the assembler Is directed to save the results of an assembly on disk, using the 
KEEP parameter. It was neccessary to supply a file name. The assembler then created 
two disk files. The first file contained the object module for the first assembled 
subroutine In the source file. (This isthe entry pointforthefinished program.) This first 
object module was saved with the file name supplied using the KEEP directive, with the 
suffix .ROOT added to the end. Forexample, if thefile nameOBJECT was used, the first 
subroutine would be saved in a file called OBJECT.ROOT. The remaining subroutines 
are placed in a file called OBJECT.A. They are placed In this file in the order that they 
occurred in the source file. 

After assembling the complete program, there may be a need to reassemble a few of the 
subroutines, using the NAMES= (n1 ,. . nx) assembler option. When this Is done, the 
assembler searches the output disk for an old file with the same root name. If this was 
the second assembly, it would find the file called OBJECT.A. The newly assembled (or 
re-assembled) subroutines are saved in a file called OBJECT.B. They appear in the 
order in which they were encountered in thesource file. Subroutines which were not re¬ 
assembled are not placed in the new file. The next partial assembly be stored in a file 
with the name OBJECT.C, and so on. 

If the first subroutine Is reassembled, it Is placed in a separate file called 
OBJECT.ROOT, replacing the first file by that name. 
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Subroutine Selection 

When a link edit starts, the same KEEP file name as used by the assembler must be 
provided. (This is done automatically by ASML and similar commands.) In the above 
example, this was OBJECT. The link editor scanstheoutputdiskforafilewiththename 
OBJECT.ROOT, using the subroutine in that file as the first subroutine in the final 
binary load module. It then locates the last object module assembled by finding theflle 
with the highest alphabetical suffix. (It does this by scanning successively for files with 
ascending alphabetic suffixes.) I n the example above, this was OBJECT.C. Subroutines 
are taken from this file in the order encountered, linked and then placed in the load 
module. The link editor then proceeds to the previous file - that is, the one with 
preceeding alphabetical suffix. If a subroutine is found which has not yet been linked, it 
Is placed in the load module. If the subroutine has already been linked, having been 
found in a previous (hence more recently assembled) file, it is ignored. Thus, the most 
recent version of a subroutine is selected automatically. 

If there are still unresolved external references, the link editor assumes that these are to 
be resolved from library files. Library files have the same format as other object 
modules, but always have a file name that begins with the characters “SUBLIB.”. The 
link editor searches the output disk for library files. If it cannot find any, it searches all of 
the disks that are on line. If it still cannot find any. It prompts with the message 

Place library files on line 

The linker waits for a key to be pressed, and then scans the active drives again. If there 
are still no library files to be found, the linker assumes that the unresolved references 
are errors. 

When a disk containing a library file is found, each library file is searched once. In the 
order in which it appears in the catalog. If any subroutine has a name or entry point 
corresponding to an unresolved reference. It is placed In the load module. A subroutine 
selected in this manner can have Its own unresolved references, which can then be 
resolved during the rest of the library search. 

Having found all of thesubroutines it can, the link editor proceeds to pass two of the link 
edit. During pass one, the link editor kept careful track of which volumes It used; during 
pass two, any volumes needed again will be asked for by number. The output file Is a 
binary file with the keep file name as Its file name. If there are no errors, the program Is 
ready to be executed using the BRUN command. 


Link Edit Command Parameters 


Several link edit options are available. These are entered as parameters to the LINK 
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command. They may appear in any order, and must be separated by commas. 
Remember that a file name must be used with the LINK command; the file namecomes 
after the LINK command, followed by the parameters. The following are valid 
commands: 

LINK MYFILE,KEEP=MYFILE,0RG=$8000,V64 
LINK MYFILE, ERROR OFF,LIST OFF , V65,KEEP =SAVE 

KEEP=xxx - Keep Output File 

The binary output file (load module) Is saved on disk using the file name xxx. This file 
can then be executed using the BRUN command from either the ORCA/M operating 
system or Apple DOS. 

ORG=org - Set Origin 

The finished program will start at location org. The value of org may be coded In decimal 
or hexadecimal. If hexadecimal Is used, the value must begin with a $ character. 

LIST OFF - Don’t List Output 

Normal output from the link editor is suppressed. Only errors are listed. 

PRINT ON - Print Output 

The text output from the link editor is sent to the printer. 

SYMBOL OFF - Don’t List Symbol Table 

The global symbol table which is normally listed at the end of the link edit output Is 
suppressed. 

Vxxx - Volume Parameter 

Volume xxx is used as the Input volume number for the object modules, and as the 
output volume number for the completed binary file. 


Predefined Labels 


The link editor automatically defines two special global labels. They are HIMEM and 
LOMEM. If a program defines a label by one of these names, the label define In the 
program has precedence. Otherwise, LOMEM is set to the first byte past the end of the 
load module created, and HIMEM is defined as the first byte used by DOS 3.3 in its 
standard configuration ($9600). 
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Creating Library Fiies 


Several library files are included with the assembler, ready to be used automatically by 
the link editor. New library files can also be created. Begin by writing a source file as if 
the library subroutines were part of a main program. A dummy subroutine is then placed 
at the start of the file. This first subroutine will be placed into the root file by the 
assembler (the one that ends In .ROOT). Assemble the file normally, as if It were a 
program. The root file is simply deleted, and the secondary file (which ends in .A) may 
be renamed as desired, provided it starts with the prefix SUBLIB. 

All subroutine libraries needed for a given link edit must be on the same disk for the link 
editor to find them. 


Output 


In addition to generating the load module, the link editor produces printed output, 
showing exactly what it did. This output can be suppressed by turning off the assembler 
output, except for errors and the global symbol table. Errors may be suppressed by 
likewise turning off assembler error massages. The global symbol table Is suppressed 
by using SYMBOL OFF. 

Refer to the listing of the operating system for examples of link edit output. 

Pass one output 

During pass one, the link editor gives the location, length and name (in that order) of 
each subroutine and data area found. The message containing the name also tells if the 
file was a subroutine or data area. If errors are found during pass one, the error message 
appears after the subroutine header message. 

Pass two output 

Pass two behaves the same way as pass one; errors are printed after the subroutine 
header messages. The subroutine header message again appears for each subroutine 
or data area, giving the name of the file, its location in the binary output file, its length 
and a note telling if the file was a subroutine or a data area. 

Global Symbol Table 

The listing concludes with an alphabetized global symbol table. Each symbol is 
followed by the value assigned to it, given In hexadecimal. 
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This value is followed by a single hexadecimal digit. The digit is zero if the label is a 
subroutine name or global label. If the label was defined in a data area, the digit is 1 
through F, and indicates the number of the data area that defined it. 

File Length and Error Count 

After the global symbol table has been printed, the link editor prints a message stating 
the number of errors (if any), and what the highest error level was. (Error levels are 
explained in appendix A.) This message is not printed if there were no errors. The last 
line tells where the program starts and how many bytes long it is, in hexadecimal. 
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Chapter Six 

The Macro and Subroutine Libraries 

Introduction 


This section is a reference guide to the macro libraries supplied with the system. It also 
provides instruction in the use of these macros. A macro library is simply a collection of 
standard macros that may be used to perform common functions. The system provides 
macros for input, output, math, logical operations, and graphics. 

Although It is expected that these macros will prove quite helpful for a variety of 
applications, there is nothing sacred about a library macro. If a macro does not suit a 
particular application, changing it isalwaysan option. However, care must betaken that 
two macros by the same name are not made available to the same program at the same 
time. If this happens, there is no easy way to predict which of the two macros will be 
used for a particular macro expansion. In fact, one form could be used in one place and 
another form In another place. 

On the SUBLIB SOURCE disk supplied with the assembler, there areseveral files which 
begin with SUBS. These are the subroutine libraries which are used by the macros In the 
macro library. They serve the dual purpose of providing examples on the use of the 
assembler and giving Immediate capability for doing common math and interface 
functions. 

The SYSTEM SOURCE disk contains a number of files which begin with MACLIB. 
These are the macro libraries themselves. 
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Using Macros in a Program 

Fortunately, it isn’t neccesary to know how to write a macro in order to use one. This 
section will show how to use the macros contained in the macro library in a given 
program. The ADD macro, (described on page 121) will be used as an example. 

Consider how two two-byte signed integers are added If macros are not used. Assume 
that NUM1 is to be added to NUM2, and the result saved in NUM3. The following 
instructions would be coded: 


CLC 

LDA 

NUMl 

ADC 

NUM2 

STA 

NUM3 

LDA 

NUMl+1 

ADC 

NUM2+1 

STA 

NUM3+1 


This is a bit verbose and clumsy for such a simple operation. Exactly the same thing 
could be accomplished with 

ADD NUMl,NUM3,NUM3 

The assembler generates the same seven Instructions that were written above, but only 
a single line need be typed. As indicated in the description of the macro, a label may be 
put in the label field. This is true of all macros in the macro library. 

Macros need not be limited to doing only one thing. Use of conditional assembly 
statements in the macro definition lets one macro do a number of slightly different 
tasks. As an example, assume that the result is to be stored back into NUM1, instead of 
NUM3. Page 000 explains that the third item In the operand field is optional. The macro 
could also be written as: 


+ 

ADD 

CLC 

NUM1,NUM2 

+ 

LDA 

NUMl 

+ 

ADC 

NUM2 

+ 

STA 

NUMl 

+ 

LDA 

NUMl+1 

+ 

ADC 

NUM2+1 

+ 

STA 

NUMl+1 


Statements that start with a “plus” (+) character are statements generated by the 
assembler when It expands the macro. They are printed in the assembly listing if the 
GEN ON directive is used (see chapter four, section three); otherwise the assembler 
prints only the macro call statement itself. 
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The description of the macro says that AD3 may be a multiple operand. This means that 
the third operand can specify more than one place to storethe resultof the addition. To 
store the result in NUM1, NUM2 and NUM3, the macro call would be coded like this: 


+ 

ADD 

CLC 

NUM1,NUM2,(NUM1,NUM2,NUM3) 

+ 

LDA 

NUMl 

+ 

ADC 

NUM2 

+ 

STA 

NUM3 

+ 

STA 

NUM2 

+ 

STA 

NUMl 

+ 

LDA 

NUMl+1 

+ 

ADC 

NUM2+1 

+ 

STA 

NUM3+1 

+ 

STA 

NUM3+1 

+ 

STA 

NUMl+1 


Enclosing the three locations in parenthesestold the macro that all three locations were 
to be used; internally, the third symbolic parameter was subscripted. 

Macro operands are not limited to labels for absolute addresses. They may contain any 
character but a blank, equal sign, or comma. An element of an operand cannot start with 
a left parenthesis, but it can have one internally. Any of these characters can be used if 
they are enclosed In single quote marks. For example, the macro 

PRINT ' 

is valid. It would print the characters (=, on the screen. In the case of the ADD macro, 
note that the description states that AD2 may be an immediate operand. Thus, to add 4 

to NUM1: 


+ 

ADD 

CLC 

NUMl,#4 

+ 

LDA 

NUMl 

+ 

ADC 

#<4 

+ 

STA 

NUMl 

+ 

BCC 

SL2 

+ 

+ SL3 

INC 

ANOP 

NUMl+1 


This expansion indicates a little morethan simply howto use immediate operands inthe 
ADD macro. Notice that the macro has used a fairly standard short cut to make the add 
three bytes shorter than if it had been written as 

CLC 

LDA NUMl 

ADC #4 




104 


ORCA/M 


STA NUMl 

LDA NUMl+1 

ADC #0 

STA NUMl+1 

This optimization would likely not be apparent unless the GEN ON directive had been 
used. The system macros make every effort to generate the most efficient code 
possible. 

In the examples so far, positional parameters have been used. This means that the 
macro knows what operands to uses by the position they occupy in the operand field of 
the macro call. The macro definitions determined that NUM3 was the place to storethe 
answer because NUM3 was the third address coded. There is another way to match 
values with the macro’s parameters. Note that the macro description lists the operands 
for the ADD macro as 


ADD ADI,AD2,AD3 

Each operand may be set manually to the desired address. This is done using keyword 
parameters. The following examples illustrate this; each line would have identical 
macro expansions. 

ADD NUM1,NUM2,NUM3 

ADD AD1=NUM1,AD3=NUM2,AD3=NUM3 

ADD AD3=NUM3, ADl^UMl, AD2=NUM2 

ADD AD3=NUM3, NUM2, ADI =NUM1 

The last example shows that keyword parameters may be mixed with positional 
parameters. Notethat keyword parameters are still counted when determining position. 
NUM2 occupies the second position, even though it was the first positional parameter 
used. 

This concludes the examples how to use macros in a program. The next section 
explains how to include the macros themselves. 

The following list of macros are ones that tend to be used often. They provide a good 
starting place for learning the library. 


ADD 

two byte integer add 

DIVD 

two byte Integer divide 

MULT 

two byte integer multiply 

SUB 

two byte integer subtract 

BGT 

branch if greater than 

BLE 

branch if less than or equal 

DBNE 

decrement and branch if not equal 

DBPL 

decrement and branch if plus 
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CMP2 

two byte compare 

DEC2 

two byte decrement 

INC3 

two byte increment 

JCC 

jump if carry clear 

JCS 

jump if carry set 

JEQ 

jump If equal 

JGE 

jump if greater than or equal 

JLT 

jump if less than 

JMI 

jump if minus 

JNE 

jump If not equal 

JPL 

jump if plus 

GOUT 

output a character 

HOME 

home cursor and clear screen 

INPUT 

input with prompt 

PRBL 

print blanks 

PRINT 

print 

PRINT2 

print without return 

RDKEY 

read keyboard 

BELL 

sound bell 

LA 

load address 

LM 

load memory 

MOVE 

move memory 


Managing Macro Libraries 


To use a library macro, all that need be done is include an MCOPY directive for each 
library needed. The format for the MCOPY directive is explained in the section three of 
the Assembler chapter. The macro descriptions are divided into sections, with each 
section corresponding to a disk file on the system disk. For example, assume that the 
ADD macro is used in a program. The introduction to that section explains that thetwo 
byte integer macros are in the macro library file called MACLIB.INTMATH. Since the 
system macros are on volume 101, (If a copy of the original distribution disk is being 
used), the statement 


MCOPY MACLIB.INTMATH,V101 

should be Included before the first use of the ADD macro. Normally, all MCOPY 
statements should be placed at the beginning of the program, immediately after the 
KEEP directive. 

Although this is the simplest way to use the macro libraries, it is not the best. If macros 
from more that one library are being used, the assembler must search these libraries 
each time it encounters a macro. As only one macro library can be held In memory at a 
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time, this means that a disk read is required each time a library is searched. The 
assembler handles this without any problem, but the amount of time required to 
assemble a program will increase considerably. 

To remedy this, it is best to create a unique macro file for each program consisting of 
only the macros used by the given program. Eliminating unneeded macros usually cuts 
the number of macro files to one, and almost always keeps them at one or two. 

To create this macro file, start by making a list of all of the macros the program uses. 
One way to do this is to assemble the program without including any MCOPY 
statements, and recording all of the operation codes the assembler flags as undefined. 
Next, load the first macro library into memory and delete all unneeded macros using the 
editor. Append the next macro library to the macros that have been left using the 
monitor APPEND command, and again delete the unused macros from that file. Repeat 
this process until all of the macros that are needed have been found. The resulting 
macro file may then be saved under a new filename for use the program under 
development. 

To do this. It is neccessary to know how to recognize and identify a macro In a source 
file. Every macro begins with a MACRO directive and ends with a MEND directive. The 
line right after the MACRO directive is called the macro definition. If a macro instruction 
Is to be included in a program, all of the lines from the MACRO directive to the MEND 
directive must be placed In the macro file that is used by the program. 

Always check a macro file to be sure that it is not over-filled. If it is over-filled, the 
assembler will wipe out the operating system when it tries to load the macro file. To 
check the macro file, use the monitor’s FREE command or ESC F from the text editor. 
The file must be less than 100% full; if It is not, divide it Into two smaller files. To minimize 
the number of disk loads that the assembler must do, divide the files so that as many 
macros as possible are in the first file that an MCOPY statement Is issued for. 

Subroutine Library Conventions 

The subroutine libraries that are used with the math and output macros follow a number 
of conventions which must be respected to avoid conflict with user programs. 

The first Is the naming convention. All subroutines and alternate entry points begin with 
the letters SYS, generally followed by a four letter descriptive name. 

In addition, many macros define labels internally. These always consist of the letteres 
SYS followed by an alphabetic character and zero to five numeric digits. User defined 
lables using the same format could cause a duplicate label error. 


The character output routine for WRITE and PRINT macros is SYSRITE. This 
subroutine requires two two-byte areas In zero page. The equates in the data area 
COMMON set these at $FC and $FE. They are called RETADand CHRAD, respectively. 
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The two byte integer math subroutines make use of a four byte section, a two byte 
section, and a single byte of zero page memory. M1L and M1H ($D0,$D1) are used as 
the location for the first argument of multiply, divide, mod and square root operations. 
M2L and M2H ($D2,$D3) are used as extended space to give room for manipulating the 
thirty-two bit intermediate results in multiply and divide operations. These four bytes 
must be sequential. M3L and M3H must also be sequential; they form the second 
argument for multiply and divide operations. They are located at $D4 and $D5. The sign 
flag is called SIGN, and is currently located at $D6. It does not need to be zero page. 

The floating point subroutines make use of the two byte Integer registers as temporary 
work space. They also use the first sixteen bytes of zero page for the same purpose. The 
first sixteen bytes are called RO, R1, R2, R3,..., R14, R15 In the COMMON data area. 
These must be sequential, but can be moved if they remain in zero page. Finally, the 
floating point subroutines use two floating point registers called FR1 and FR2. These 
must be in zero page. The first is eleven bytes long and the second eight bytes long. 

The double precision routines also use two floating point registers. Both must be In zero 
page. They are still called FR1 and FR2, and may be located so as to overlap the single 
precision registers. The first is twenty bytes long, and the second is twelve bytes long. 

Four byte integer subroutines make use of the registers defined for two byte integer 
subroutines, using them as work space. The first eight bytes of FR1 is used as the 
double length first argument, serving the same purpose as M1L, M1H, M2L, and M2H for 
the two byte routines. The first four bytes of FR2 are used for the second argument. 

The subroutines SYSDOPR and SYSFOPR are used by the macro library to load FR1 
and FR2 with the needed floating point arguments, and to save the result In the proper 
spot when completed. They require two two byte registers in zero page memory. The 
first Is at $E8, and the second at $EA. They are called AD1 and RAD, respectively. Both 
single and double precision subroutines also makefree use of the first ninety-two bytes 
of page three ($300 to $35C) as work space. 

The last zero page location used is FERR, located at $F7. It can be changed to a non¬ 
zero page address. This location is Initialized by SYSDOPR and SYSFOPR, which are 
called by all of the floating point macros that use the subroutine library. On return from 
the library subroutines, FERR contains the error code. Calling SYSFERR after a 
floating-point operation, (also located in the subroutine library) prints the appropriate 
error message. If FERR=0, there was no error and SYSFERR does not print anything. 
User programs can intercept errors simply by checking FERR. The error numbers and 
their meaning are summarized below. 

All of the areas listed here may be stored to in a user-written program. The subroutine 
library does not depend on their Initial values. However, these areas may be changed 
when a library subroutine is called. If these areas interfere with a user program, they 
may be moved. Make the changes in the COMMON data area at the beginning of the 
subroutine library, then reassemble the library. Also, RO, R1, M1L, M2L, M3L, FERR, 
FR1, and FR2 must be defined in the user program with the same values as found in the 
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COMMON data area. The new definitions provided will override the defaults set by 
some of the macros. See individual subroutines for more detail on memory usage. 


Macro Descriptions 


The macro descriptions have several parts. The header contains the name of the macro 
and a brief title. The next line is the form of the macro. The label names used in this 
model line correspond to the names of the symbolic parameters in the macro 
definitions, and can therefore be used as keyword names. Next comes a description of 
each argument in the macro. Last is a description of the capabilities of the macro. 

Floating Point Macros 

This section describes the macros that are used to call the floating point routines 
available either in SUBLIB.SYSTEM, or the ones resident in the Applesoft ROM. The 
routines actually used are selected by which macro library is used when the program is 
assembled (using MCOPY ). The single precision floating point macros are contained in 
the file MACLIB.FPMATH.SUBS, the Applesoft ROM routines are in MACLIB.FPMATH.ROM, 
and the the double precision macros are in MACLIB.DPMATH.SUBS. 

The floating point library supports both single and double precision floating point 
arithmetic. The ROM routines are of course limited to single precision, as in Applesoft. 
(If the ROM routines are used, there must be a copy of Applesoft in memory when the 
program using these routines is executed.) The form of the macro operands for both the 
ROM Applesoft and the subroutine library single and double precision macros are 
identical, and the operation codes are either identical or nearly identical. For this 
reason, they are all described together, and generally only the single precision macros 
are detailed. 

Each macro description begins with three lines which Indicate the model form for a 
macro call. The order they are listed in istheROM form first, followed by the subroutine 
library single- and double-precision forms. If there is no corresponding form for a given 
macro, there is a dash on the respective line. Although the ROM and subroutinesingle- 
precision macros have been designed so that, generally speaking, the same source can 
be re-assembled simply by changing the MCOPY statement, there are some differences 
which are noted In the text. 

The primary difference between the ROM routines and the subroutines Is that the 
subroutines provide built-in error handling, while the ROM routines do not. Also, the 
ROM I/O routines clear the high order bit of ASCII characters, while the library routines 
set it. 
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Remember that single precision numbers are five bytes long, while double precision 
variables require ten bytes. 

The source code for the subroutines is on the SUBLIB.SOURCE Disk. The single 
precision routines are in the five files that start SUBS.FPMATH. The double precision 
subroutine files start with SUBS.DPMATH. They are assembled Into SUBLIB.SYSTEM, 
which will be searched automatically by the link editor for unresolved references If the 
system disk is on line at link edit time. 

The floating point macros may change one or more of the following locations: $00 to 
$0F, $D0 to $FD, $300 to $35C. These areas may also be used within a program, but will 
not retain their values across a floating point call. The macros also may define one or 
more of the following global labels. These label names should not be used within a 
program. If one of the names listed is defined. It will override the definitions In the 
macros themselves. If changes are made to any of these locations. It must be done both 
in the program itself and in the subroutine library common area. 

MIL $D0 integer math register one 

FERR $D7 floating point error number 
FRl $DC Floating point register one 

If the floating point routines encounter an error condition, they set FERRtothe number 
of the errorfound. If noerrorwas encountered, FERR issettozero. Possible error codes 
and their meanings include 

Code Meaning 

1 Argument too large in SIN or COS 

3 Exponent Underflow 

3 Illegal argument in LN(X) 

4 Division by Zero 

5 Exponent Underflow 

6 Negative Argument in Square Root 

The library includes a subroutine called SYSFERR. This routine will print the 
appropriate error message if an error occurred In the last floating point operation, and 
will do nothing if there was no error. To use the subroutine, simply place a 

JSR SYSFERR 

after any floating point or double precision macro where an error might occur. The 
subroutine will automatically be included in the program by the link editor. 

Single precision floating point numbers can range from about 1E-38 to 1E38. Double 
precision numbers range from about 1E-9864 to 1E9864. 
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ABS ATAN CHRGET 


ABS - Absolute Value 

LAB ABS ADI 

LAB ABS ADI 

LAB DABS ADI 

LAB - label 

ADI - argument and result 

The absolute value of the floating point number at by ADI is stored at AD1. 


ATAN - 

■ Arc Tangent 

LAB 

ATAN 

AD1,AD2 

LAB 

ATAN 

AD1,AD2 

LAB 

DATAN 

AD1,AD2 

LAB 

- label 


ADI 

- argument 

AD2 

- result 



The arc tangent of the floating point number at ADI is placed in AD2. If AD2 is not 
coded, the result is placed in ADI. The result is returned in radians, with a range of-7r/2 
to 7r/2. 

CHRGET - Character Input Initialization 

LAB CHRGET 
LAB CHRGET 


LAB - label 

Prior to the first use of FPIN when the ROM library is being used, the CHRGET macro 
must be called to Initialize the Applesoft character Input routine. The CHRGET macro is 
only needed once unless locations $00B1 to $00C8arechanged. In that case, CHRGET 
must be used again to restore the character input routine that it builds in those memory 
locations. 

In the subroutine macro library, this macro issimply adummy sothatthesame program 
may be written to use the Applesoft floating point routines or the subroutine library. 
Since the initialization called for Is not needed forthe subroutine libraries, it expands to 
an ANOP directive. 
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CHS _COS CNVDF 


CHS - Change Sign 

LAB CHS ADI 

LAB CHS ADI 

LAB DCHS ADI 

LAB - label 

ADI - address of number 

Place the negative of the floating point number in ADI back into ADI. 

COS - Cosine 

LAB cos AD1,AD2 

LAB COS AD1,AD2 

LAB DCOS AD1,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The cosine of the floating point number at ADI isplacedat AD2. If AD2isnotcoded, the 
result Is placed back Into ADI. The argument must be in radians. 

If the subroutine library routines are used and the absolute value of the argument is 
greater than 205887 (13493037704 for double precision) then FERR Is set to one and no 
action is taken. This is because the answer would not bevalid after multiples of 2 tt were 
subtracted to reduce the number to the range Oto 2 tt. 

CNVDF - Convert Double Precision to Floating Point 


LAB CNVDF DP,FP 
LAB - label 

DP - double precision number 
FP - floating point number 

Converts the double precision number pointed to by DP into a single precision number 
and stores it at FP. If exponent overflow occurs, the overflow flag Is set. This macro is 
found only In MACLIB.DPMATH. 
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CNVFD EXP FADD 


CNVFD - Convert Floating Point to Double Precision 


LAB 

CNVFD FP,DP 

LAB - 

FP - 

DP - 

label 

floating point number 
double precision number 


Converts the floating point number pointed to by FP Into a double precision number 
and stores it at DP. This macro is in MACLIB.DPMATH. 

EXP - Exponent 


LAB 

EXP 

AD1,AD3 

LAB 

EXP 

AD1,AD2 

LAB 

DEXP 

AD1,AD3 

LAB - 

label 


ADI - 

argument 

AD3 - 

result 



The floating point number pointed to by AD1 is exponentiated and placed at AD2. If AD2 
is not coded, the result is placed In ADI. 

If the library subroutines are used and the operation results in a number too large to 
represent, FERR is set to two. 


FADD 

- Floating Point Add 

LAB 

FADD 

AD1,AD2,AD3 

LAB 

FADD 

AD1,AD2,AD3 

LAB 

DADD 

AD1,AD2,AD3 

LAB 

- label 


ADI 

- first argument 

AD2 

- second argument 

ADS 

- result 



The floating point numbers at ADI and AD2 are added. The result is placed in AD3 if It Is 
coded, and ADI If It is not. 

If the library subroutines are used and the operation results In a number too large to 
represent, FERR Is set to two. 




THE LIBRARIES 


113 


FDIVD FERR 


FIX 


FDIVD - Floating Point Divide 

LAB FDIVD AD1,AD2,AD3 

LAB FDIVD AD1,AD2,AD3 

LAB DDIVD AD1,AD3,AD3 

LAB - label 
ADI - numerator 
AD2 - denominator 
AD3 - result 

The floating point number at AD1 is divided by the number at AD2. The result is placed 
in ADS if It Is coded, and in ADI If It Is not. 

If the library routines are used and a division by zero is attempted, FERR issettofour. If 
the operation results In a number too large to represent, FERR is set to two. 

FERR - Set Floating Point Error 

LAB FERR ADR 

LAB - label 

ADR - error number 

ADR is placed at the location FERR. This macro Is used by the floating point routines to 
set the error number when an error is detected. It should also be used by any user- 
written subroutine which detects floating point errors. For example, if a subroutine to 
compute base ten logarithms were to be written. It should use the FERR macro if the 
input were zero or negative. 

FIX - Convert to Integer 

LAB FIX AD1,AD2 
LAB FIX AD1,AD2 
LAB DFIX AD1,AD2 

LAB - label 

ADI - number to fix 

AD2 - result 

The floating point number at ADI Is converted intoatwo bytesigned Integer and stored 
at AD2. If the result Is outside the valid range for an Integer (-32768 to 32767) then the 
overflow flag is set. 



114 


ORCA/M 


FIX4 FLOAT FLOAT4 


FIX4 - Convert to 4 Byte Integer 


LAB FIX4 AD1,AD2 
LAB DFIX4 AD1,AD2 

LAB - label 

ADI - number to fix 

AD2 - result 

The floating point number at ADI is converted into a two byte signed integer and stored 
at AD2. If the result is outside the valid range for an integer 
(-32768 to 32767) then the overflow flag is set. 

FLOAT - Convert from Integer 


LAB 

FLOAT 

AD1,AD3 

LAB 

FLOAT 

AD1,AD2 

LAB 

DFLOAT 

AD1,AD2 

LAB - 

label 


ADI - 

number to float 

AD2 - 

result 



The two byte signed integer pointed to by AD1 Is converted into a floating point number 
and stored at AD2. 

FLOAT4 - Convert from 4 Byte Integer 


LAB FL0AT4 ADI,AD2 
LAB DFL0AT4 AD1,AD2 

LAB - label 

ADI - number to float 

AD2 - result 

The four byte signed Integer pointed toby AD1 Is converted Intoafloating point number 
and stored at AD2. 
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FMULT 


FPIN 


FMULT - Floating Point Multiply 

LAB FMULT AD1,AD2,AD3 

LAB FMULT AD1,AD2,AD3 

LAB DMULT AD1,AD2,AD3 

LAB - label 
ADI - first argument 
AD3 - second argument 
AD3 - result 


The floating point numbers pointed to by ADI and AD2 are multiplied. The result Is 
placed at AD3 if it Is coded and at ADI If it Is not. 

If the library routines are used and the operation results In a number too large to 
represent, FERR is set to two. 


FPIN - 

Floating 

Point Input 

LAB 

FPIN 

ADR,STRING 

LAB 

FPIN 

ADR,STRING 

LAB 

DPIN 

ADR,STRING 

LAB - label 

ADR - result 

STRING - String to convert 


The string of characters stored at STRING Is converted to a floating point number and 
stored at ADR. 

If the ROM macros are used, the string must end with a binary zero. The CHRGET 
macro must first have been called to Initialize the Input routine. The string must be in 
ASCII with high-order bit set to zero. 

If the library subroutines are used, the string is considered terminated when the first 
non-numeric character is encountered. The numeric characters include the ten decimal 
digits, +, -, blank, decimal point (.), and E. E signals the beginning of the exponent. A 
second E would signal the end of the number. 
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FPOUT FSUB 


FPOUT - Convert Binary to String 

LAB FPOUT ADI 
LAB FPOUT ADI 
LAB DPOUT ADI 

LAB - label 
ADI - argument 

The floating point number pointed to by AD1 is converted to a string. 

If the ROM macro is used, the string consists of ASCI I characters with the high-order bit 
set to zero and is stored at $100-$110. The string ends with a binary zero. The address of 
the string is contained in A (low-order byte), Y (high-order byte). 

If the library routines are used, the string consists of screen characters, that is, ASCII 
with high-order bit set to one. The string ends with abinary zero. The result is stored in a 
buffer contained within the subroutine. The address of the string is contained in A (low- 
order byte), Y (high-order byte). PRNUM may be used afterthis macroto send the string 
to the current output device. 

FSUB - Floating Point Subtract 

LAB FSUB AD1,AD2,AD3 
LAB FSUB AD1,AD2,AD3 
LAB DSUB AD1,AD3,AD3 

LAB - label 

ADI - number to be subtracted from 
AD2 - number to subtract 
AD3 - result 

The floating point number at AD2 is subtracted from the number at ADI. 


If AD3 Is coded, the result is stored there; if it is not coded, the result is stored at ADI. 

If the library routines are used and the operation results in a number too large to 
represent, FERR is set to two. 
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INT 


LN 


PWR 


INT - Floating Point Integer Function 

LAB INT AD1,AD3 

LAB INT AD1,AD2 

LAB DINT AD1,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The largest integer of the floating point number pointed to by ADI is placed at AD2. If 
AD2 is not coded, the result is placed at AD1. 

LN - Natural Logarithm 

LAB LN AD1,AD2 

LAB LN AD1,AD2 

LAB DLN ADI,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The natural logarithm of ADI is placed at AD2. If AD2 is not coded, the result is placed 

at AD1. 

If library routines are used and the argument is zero or negative, FERR is set to three. 


PWR - 

Raise a Number to a Power 

LAB 

PWR 

AD1,AD2,AD3 

LAB 

PWR 

AD1,AD2,AD3 

LAB 

DPWR 

AD1,AD2,AD3 

LAB 

- label 


ADI 

- number 

AD 2 

- power 

ADS 

- result 



Raise thefloating point numberat AD1 tothe powerof thefloating point number at AD2. 
The result is placed at AD3 if it was coded, and at AD1 otherwise. 

If the library routines are used and the numberat ADI is zero or negative, FERR issetto 
three. If the operation results In a number too large to represent, FERR is set to two. 
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SIGN SIN 


SIGN - Sign Function 

LAB SIGN AD1,AD2 

LAB SIGN AD1,AD2 

LAB DSIGN AD1,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The result Is -1 if ADI is less than zero, 1 if it Is greater than zero, and 0 if ADI is zero. The 
result is placed at AD2 if AD2 is coded, and at ADI if it is not. 

SIN - Sine 

LAB SIN AD1,AD2 

LAB SIN AD1,AD2 

LAB DSIN AD1,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The sine of the floating point number pointed to by ADI is placed at AD2 If AD2 is coded, 
and at ADI if it is not. The argument must be in radians. 

If the library subroutines are used and the absolute value of the argument is greater than 
205887 (13493037704 for double precision numbers) then FERR is set to one and no 
action is taken. This is because the answer would not be valid after multiples of 2 Trwere 
removed to bring the range of the argument between 0 and 2 tt. 
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SQR 


TAN 


SQR - Square Root 


LAB 

SQR 

AD1,AD2 

LAB 

SQR 

AD1,AD2 

LAB 

DSQR 

AD1,AD2 

LAB 

- label 


ADI 

- argument 

AD 2 

- result 



The square root of the floating point number pointed to by ADI is placed at AD2. If AD2 
Is not coded, the result is placed at AD1. 

If the library routines are used and the argument is negative, no action is taken and 
FERR is set to six. 

TAN - Tangent 


LAB 

TAN 

AD1,AD2 

LAB 

TAN 

AD1,AD2 

LAB 

DTAN 

AD1,AD2 

LAB 

- label 


ADI 

- argument 

AD 2 

- result 



The tangent of the floating point number pointed to by AD1 is placed at AD2 if AD2 is 
coded, and at ADI otherwise. The argument must be in radians. If the library routines 
are used and the absolute value of the argument is greater than 205887 (13493037704 
for double precision numbers) then FERR is set to one and no action is taken. This is 
because the answer wouldn’t be valid after multiples of 2 tt were removed to bring the 
argument into the range 0 to 2 tt 
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Integer Math Macros 

This group of macros provides routines for performing mathematical operations on two 
and four byte signed integers. The macros call routines in the system subroutine library. 
The source code for the two byte subroutines is in the two files that begin with 
SUBS.UTILITY. The source code for the four byte subroutines is in the two files that 
start with SUBS.INT4MATH. The macros for the two byte routines are in the file 
MACLIB.INTMATH. Macros for the four byte routines are in MACLIB.INT4MATH. 

All Integer math operations use the overflow flag to indicate errors. If the overflow flag Is 
clear, the operation was successful; If it is set, there was an error. For addition, 
subtraction, and multiplication, a set overflow flag Indicate a number overflow. In the 
case of a multiply, the sign is not set if an overflow occurs. The double length unsigned 
result starts at M1L ($D0) for two byte multiplies, and at FR1 ($DC) for four byte 
multiplies. If the overflow flag is set after a divide or modulo operation, a division by zero 
was attempted. The operation is not performed. For a square root, the overflow flag 
indicates a negative argument, and the operation is not performed. 

Two byte signed Integers range from -32768 to 32767. Four byte signed Integers range 
from -2147483648 to 2147483647. 

In the sections that follow, the two byte version of the operation Is shown on the title 
line. The model statement has two versions; the first is for two byte operations, the 
second for four byte operations. Any differences are noted in the text. 

Two byte operations may modify the zero page locations from $D0 to $D6. Four byte 
operations may modify the zero page locations $D6 to $F3, $0, and $1. 

Two byte macros may define one or more of the following global labels. User programs 
should not usethese label names. If oneofthe names listed is defined, it will overridethe 
definitions in the macros themselves. If any changes are made to any of these 
definitions, they must be done in both the user program and In the data area of the 
subroutine libraries. 

MIL $D0 integer math registers 

M2L $D2 

M3L $D4 

In addition, the four byte integer math macros may also define thefollowing constants. 

FRl $DC floating point registers 

FR2 $F0 

RO $00 general purpose register 
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ADD CNV24 CNV42 


ADD - Two Byte Integer Add 

LAB ADD AD1,AD2,AD3 
LAB ADD4 AD1,AD2,AD3 

LAB - label 

ADI - number to add 

AD2 - second number to add 

AD3 - result 

The signed integer at ADI is added to the number at AD2. If AD3 is present, the result is 
stored there; if not, the result Is stored in AD1. AD2 may bean immediate operand. ADS 
may be a multiple operand. 

CNV24 - Convert 2 Byte to 4 Byte 

LAB CNV24 12,14 

LAB - label 

12 - two byte integer 

14 - four byte integer 

Converts the two byte integer at 12 into a four byte integer, storing it at 14. 

CNV42 - Convert 4 Byte to 2 Byte 

LAB CNV42 14,12 

LAB - label 

14 - four byte Integer 

12 - two byte integer 

If the conversion is possible, the four byte integer at 14 is converted into a two byte 
Integer and stored at 12; the overflow flag is cleared. If the conversion is not possible, 12 
Is left unchanged and the overflow flag is set. 
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DIVD lABS IIN 


DIVD - Integer Divide 

LAB DIVD AD1,AD2,AD3 
LAB DIV4 AD1,AD3,AD3 

LAB - label 
ADI - numerator 
AD2 - denominator 
AD3 - result 

The signed integer at AD1 Is divided by AD2. If ADS is present, the result Is stored there; 
If not, the result is stored in ADI. ADS may be a multiple operand. For two byte 
operations, both AD1 and AD2 may be immediate operands. If ADI is an Immediate 
operand, ADS must be coded. 

lABS - Absolute Value 

LAB lABS ADI 

LAB I4ABS ADI 

LAB - label 
ADI - argument 

The absolute value of the signed integer pointed at by AD1 is stored at ADI. 

IIN - Input an Integer 

LAB IIN ADI,STRING 

LAB I4IN ADI,STRING 

LAB - label 

ADI - integer 

STRING - string to convert 

The string of Apple II screen characters (ASCII characters with high-order bit set to 
one) at STRING is converted Into a signed Integer and stored at ADI. The string may 
have a leading sign (+ or -) and any number of embedded blanks, in any position. The 
string terminates with the first non-numeric, non-blank character that was not a leading 
sign. The null string is legal, and returns a value of zero. 
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lOUT _ISIGN ISQR 


lOUT - Integer Output 

LAB IOUT ADI 
LAB I40UT ADI 

LAB - label 
ADI - argument 

The signed integer at ADI is converted into a string of screen characters, terminating 
with a binary zero. The address of the string is returned in A (low order byte), Y (high 
order byte). Leading zeros are suppressed. PRNUM may be used after this macro to 
send the string to the current output device. 

ISIGN - Integer Sign Function 

LAB ISIGN ADI 
LAB I4SIGN AD1,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The sign of the number at ADI is computed. It is stored at AD2 if It is coded, and at ADI if 
It is not. AD2 cannot be coded for a two byte operation. The result is -1 If ADI <0, 0 if ADI 
= 0 and 1 if AD1 >0. 

ISQR - Integer Square Root 

LAB ISQR AD1,AD2 
LAB I4SQR AD1,AD2 

LAB - label 
ADI - argument 
AD2 - result 

The Integer part of the square root of the integer at ADI is calculated. The result is 
stored in AD2 if It is coded, and in ADI if AD2 Is not coded. If the argument Is negative, 
the overflow flag is set and the operation Is ignored. 
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mod mult_ SUB 


MOD - Integer Modulo Function 

LAB MOD AD1,AD2,AD3 
LAB M0D4 AD1,AD2,AD3 

LAB - label 
ADI - numerator 
AD2 - denominator 
AD3 - result 

The signed integer pointed to by ADI is divided by the number at AD2. If AD3 Is present, 
the positive remainder is stored there; if it Is not, the result is placed in AD1. The signed 
result of the division is left In MIL, M1H (FR1 to FR1 + 3 for four byte operations). For 
t\NO byte operations, ADI and AD2 can both be immediate operands. If ADI Is an 
immediate operand, AD3 must be coded. AD3 can be a multiple operand. 

MULT - Integer Multiply 

LAB MULT AD1,AD2,AD3 
LAB MUL4 AD1,AD2,AD3 

LAB - label 
ADI - multiplicand 
AD2 - multiplier 
AD3 - result 

The signed integers at ADI and AD2 are multiplied. If AD3 is specified, the result is 
stored there. If AD3 is not specified, the result Is stored in ADI. AD3 may be a multiple 
operand. For two byte operations, AD2 may be an immediate operand value. 

SUB - Integer Subtract 

LAB SUB AD1,AD2,AD3 
LAB SUB4 AD1,AD2,AD3 

LAB - label 

ADI - number to subtract from 
AD2 - number to subtract 
AD3 - result 

The signed integer at AD2 Is subtracted from ADI. If AD3 is present, the result is stored 
there; If not, the result is stored in ADI. Fortwo byte operations, both ADI and AD2may 
be immediate operands. If ADI is an immediate operand, AD3 must be specified. AD3 
can be a multiple operand. 
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Logic and Branching Macros 

These macros develop logic and looping capabilities, many based on two byte 
numbers. They are independent of the subroutine library and do not need a specific 
monitor ROM version. They are found in the file MACLIB.LOGIC. All two byte numbers 
are assumed to be signed integers stored least significant byte first unless otherwise 
noted. 

ASL2 - Two Byte Arithmetic Shift Left 

LAB ASL ADR 

LAB - label 

ADR - location to shift 

The two byte value pointed to by ADR is shifted left one bit. The carry flag receives the 
bit shifted out of the most significant bit position. A zero replaces the least significant 
bit. 

BGT - Branch on Greater Than 
LAB BGT BP 

LAB - label 

BP - address to branch to 

If the positive flag is set and the zero flag is clear, do a relative branch to BP. 

BLE - Branch If Less Than or Equal 
LAB BLE BP 

LAB - label 

BP - address to branch to 

If the last operation setting the zero and minus flag resulted in a negative orzero result, 
do a relative branch to BP. 
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CMP2 DBNE DBNE2 


CMP2 - Two Byte Compare 

LAB CMP2 AD1,AD2,R 

LAB - label 
ADI - first number 
AD2 - second number 
R - register to use 

The two byte unsigned integer at ADI is compared with the two byte unsigned integer at 
AD2. The Z flag is set if they are equal and clear if they are not. The carry flag is set if ADI 
= AD2, and clear If ADI < AD2. R is optional, and If coded indicates which register to use 
for the comparison. If R is not coded, the accumulator is used. Both ADI and AD2 may 
be specified as Immediate operands. 

DBNE - Decrement and Branch if Not Equal 

LAB DBNE R,BP 

LAB - label 

R - register to decrement 
BP - address to branch to 

Decrement the one byte unsigned Integer pointed to by R and branch to BP if R Is not 
zero. R can be the X or Y register, or any memory location. 

DBNE2 - Two Byte Decrement and Branch if Not Equal 

LAB DBNE2 ADR,BP,R 

LAB - label 

ADR - points to a two byte unsigned number 
BP - label to branch to 
R - register used for comparison 

Decrement the two byte unsigned Integer pointed to by ADR. If the result Is not zero, 
branch to BP. 




THE LIBRARIES 


127 


DBPL 


DEC2 


JCC 


JCS 


DBPL - Decrement and Branch if Plus 
LAB DBPL R,BP 

LAB - label 

R - register to decrement 
BP - address to branch to 

Decrement a register or one byte memory location and branch if it is positive. R may be 
X, Y, or a memory location, and must be specified. 

DEC2 - Two Byte Decrement 

LAB DEC2 ADR,R 

LAB - label 

ADR - address to decrement 
R - register used for comparison 

The two bytes at ADR are decremented by one. The carry, zero, and minus flags are not 
set by this operation as they would be if the DEC instruction were used, but they are 
modified. 

JCC - Jump If Carry Clear 

LAB JCC BP 

LAB - label 
BP - branch point 

If the carry flag is clear, jump to BP; If it Is set, processing continues with the first 
Instruction past this one. 

JCS - Jump If Carry Set 

LAB JCS BP 

LAB - label 
BP - branch point 

If the carry flag is set, jump to BP; if it Is not, processing continues with the first 
instruction past this one. 
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JEQ 


JGE 


JGT 


JLE 


JEQ - Jump if Equal 

LAB JEQ BP 

LAB - label 
BP - branch point 

If the zero flag is set, jump to BP; if it is not, processing continues with the first 
instruction past this one. 

JGE - Jump if Greater than or Equal 

LAB JGE BP 

LAB - label 
BP - branch point 

If the carry flag is set, jump to BP; if It is not, processing continues with the first 
Instruction past this one. 

JGT - Jump If Greater Than 

LAB JGT BP 

LAB - label 
BP - branch point 

If the carry flag is set and the zero flag Is clear, jump to BP; if these conditions are not 
met, processing continues with the first instruction past this one. 

JLE - Jump if Less Than or Equal 

LAB JLE BP 

LAB - label 

BP - branch point 

If the carry flag is clear or the zero flag is set, jump to BP; otherwise processing 
continues with the instruction after this one. 
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_ ^ _JM|__ JPL 

JLT - Jump if Less Than 

LAB JLT BP 

LAB - label 
BP - branch point 

If the carry flag is clear, jump to BP; If it is not, processing continues with the first 
instruction past this one. 

JMI - Jump if Minus 

LAB JMI BP 

LAB - label 
BP - branch point 

If the minus flag is set, jump to BP; if it is not, processing continues with the first 
instruction past this one. 

JNE - Jump if Not Equal 

LAB JNE BP 

LAB - label 
BP - branch point 

If the equal flag is clear, jump to BP; If It is not, processing continues with the first 
instruction past this one. 

JPL - Jump if Plus 

LAB JPL BP 

LAB - label 
BP - branch point 

If the minus flag Is clear, jump to BP; if it Is not, processing continues with the first 
instruction past this one. 
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INC2 LSR2 MASL MLSR 


INC2 - Two Byte Increment 
LAB INC2 ADR 
LAB - label 

ADR - address to increment 

Increment the two byte number at ADR. The carry, zero and minus flags are not reliably 
set by this operation. 

LSR2 - Two Byte Logical Shift Right 

LAB LSR3 ADR 

LAB - label 

ADR - location to shift 

The two byte value at ADR is shifted right one bit. The most significant bit issettozero. 
The carry flag receives the bit shifted out of the least significant bit position. 

MASL - Multiple Arithmetic Shift Left 

LAB MASL ADR,NUM 

LAB - label 

ADR - address to shift 

NUM - number of shifts 

The location at ADR Is shifted left NUM times, filling with zeros on the right. ADR may be 
the accumulator or any valid operand for an ASL command. NUM must be a positive 
non-zero integer. 

MLSR - Multiple Logical Shift Right 

LAB MLSR ADR,NUM 

LAB - label 

ADR - address to shift 

NUM - number of shifts 

The location pointed to by ADR Is shifted right NUM times, filling with zeros on the left. 
ADR may be the accumulator or any valid operand fora LSR command. NUM must bea 
positive non-zero integer. 
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Input and Output 

These macros provide input and output functions. They are located in the file 
MACLIB.I/O. The print, writeand input macros requirethe library subroutine SYSRITE, 
assembled in SUBLIB.SYSTEM. The source code for SYSRITE is in SUBS.UTILITY2. It 
uses the zero page locations $FC to $FF. Many of these macros use the accumulator, 
and some also use X and Y. Check individual macros and see if this could cause a 
problem with a given program. 

COUT - Write Character 

LAB COUT R,C 

LAB - label 

R - location of character 
C - output type flag 

Output a character. R may be blank or a valid operand for a LDA instruction. The 
character Is placed in A and output. If C is present, output is tothe screen. If not, output 
Is to the output device pointed to by CSWL ($36). If R is omitted, the character is 
assumed to be in the accumulator already. 

CROUT - Return 

LAB CROUT C 

LAB - label 
C - clear line flag 

Issue a carriage return. If C Is present, clear to the end of the current line before issuing 
the return. 

FLASH - Set Flashing Print Characters 
LAB FLASH 
LAB - label 

Set proper flags so that COUT prints flashing characters. The accumulator is 
scrambled. 
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GETLN HOME HTAB 


GETLN - Get Input Line 
LAB GETLN WRD 
LAB - label 

WRD - flag indicating prompt or no return 

Gets an input line from the keyboard using the monitor input routines. If WRD is RET, a 
return is issued before getting the input. If WRb is NP, the return is still used, but no 
prompt is issued. If WRD is not included, neither a prompt or a return is issued. The 
prompt is the screen character contained in $33 (seethe PROMPT macro). X contains 
the length of the input line. The reply is located at $200. 

HOME - Clear Page and Home Cursor 

LAB HOME 

LAB - label 

Calls the monitor subroutine which clears thescreen and places the cursor in the upper 
left hand corner. The registers are scrambled. 

HTAB - Horizontal Tab 

LAB HTAB NUM 

LAB - label 

NUM - horizontal position 

Set the cursor to the horizontal position set by NUM. NUM should be In the range zero to 
thirty-nine, and must be a valid operand for a load register operation. The accumulator 
is scrambled. 
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INPUT INVERSE NORMAL PRAX 


INPUT - Input With Prompt 

LAB INPUT ‘CHRS» 

LAB - label 

CHRS - prompt characters 

The character string CHRS is written to the current output device. A flashing cursor is 
placed after the last character in CHRS, and an input with no prompt or return is issued, 
using the monitor input routine. X contains the length of the input line, which is located 
at $200. The character string need not be enclosed in single quote marks if it contains no 
blanks, equal signsor commas, and if the string does not start with a left parenthesis. If it 
is enclosed in single quote marks, single quote marks in the string must be represented 
by four single quote marks. The character string may be omitted, in which case the input 
is accepted without issuing a return or placing the prompt character on the screen. The 
A and Y registers are scrambled. 

INVERSE - Set Inverse Print Characters 

LAB INVERSE 

LAB - label 

Set proper flags so that COUT prints inverse characters on the screen. The accumulator 
is scrambled. 

NORMAL - Set Normal Print Characters 
LAB NORMAL 
LAB - label 

Set proper flags so that COUT prints normal characters. 

PRAX - Print A,X as a Hex Number 
LAB PRAX 
LAB - label 

Calls the monitor subroutine to print A, X as a four digit hexadecimal number. The 
accumulator is scrambled. 




134 


ORCA/M 


PRBL PRBYT PRERR PRHEX 


PRBL - Print Blanks 
LAB PRBL NUM 
LAB - label 

NUM - number of blanks 

Print blanks on the current output device. If NUM Is not specified, one blank is printed. If 
NUM IsX, the number of blanks inX are printed. Any othervaluefor NUM must beavalld 
operand for a LDX instruction. If X or NUM is zero, 256 blanks will be printed. 

PRBYTE - Print the Accumulator in Hex 

LAB PRBYTE ADR 

LAB - label 

ADR - address of byte to print 

Calls the monitor subroutine to print the accumulator as a two digit hexadecimal 
number. If ADR Is not coded, the byte to print must be in the accumulator. The 
accumulator is scrambled. 

PRERR - Print Error Message 

LAB PRERR 

LAB - label 

Calls the monitor subroutine to print ’ERR’, after which the bell is sounded. The 
accumulator Is scrambled. 

PRHEX - Print a Hexadecimal Digit 

LAB PRHEX ADR 

LAB - label 

ADR - address of digit 

Calls the monitor subroutine to print the accumulator as a single hexadecimal digit. If 
ADR Is not specified, the digit must be in the accumulator. The accumulator is 
scrambled. 
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PRNUM_PROMPT PRINT 


PRNUM - Print a Number 
LAB PRNUM 
LAB - label 

Output routine to print out number strings after the number string has been formed by 
one of the number output routines. It must be called before the registers are changed. 

PROMPT - Set Prompt Character 

LAB PROMPT CHAR 

LAB - label 

CHAR - prompt character 

The prompt character CHAR is placed at $33. CHAR must be a valid operand for a LDA 
Instruction. If missing, the prompt character must be in the accumulator. Further use of 
the monitor input routine will use the prompt character specified. 

PRINT - Print Characters with Return 

LAB PRINT ‘CHRS» 

LAB - label 

CHRS - character string to print 

Print the characters on the current output device, followed by a return. The characters 
need not be enclosed In single quote marks If there are no embedded blanks, commas 
or equal signs, and If the string does not start with a left parenthesis. Four single quote 
marks must be used for each single quote mark enclosed in single quote marks. If the 
character string is omitted, a return Is issued without printing any characters. All 
registers are scrambled. 
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PRINTC PRINT2_RDKEY 


PRINTC - Print Centered Characters with Return 
LAB PRINTC ‘CHRS’ 

LAB - label 

CHRS - character string to print 

Print the characters on the current output device, followed by a return. The characters 
are preceded with enough blanks to center the characters on a 40 column screen. The 
characters need not be enclosed In single quote marks ifthere are no embedded blanks, 
commas or equal signs, and if the string does not start with a left parenthesis. Four 
single quote marks must be used for each single quote mark enclosed in single quote 
marks. All registers are scrambled. 

PRINT2 - Print Characters Without Return 

LAB PRINT2 ‘CHRS» 

LAB - label 

CHRS - character string to print 

Print the characters on the current output device, with no return. The characters need 
not be enclosed in single quote marks if there are no embedded blanks, commas or 
equal signs, and if the string does not start with a left parenthesis. Four single quote 
marks must be used for each single quote mark that is enclosed in single quote marks. 
All registers are scrambled. 

RDKEY - Read a Character 

LAB RDKEY CRS 

LAB - label 
CRS - cursor flag 

A character is read from the keyboard. If CRS is not present, no cursor is placed on the 
screen, but it Is removed after the cursor is read. If CRS Is specified, a cursor Is placed 
on the screen before calling the standard input routine whose address is at KSW ($38), 
usually the same routine called If CRS is not specified. If CRS is specified as NO, a 
cursor is not placed on the screen, and the monitor input routine is used. 
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VTAB WNDB WNDL WNDT 


VTAB - Vertical Tab 

LAB VTAB NUM 

LAB - label 
NUM - line number 

Set the vertical cursor position to NUM, which should be In the range zero to twenty- 
three. NUM must be a valid operand for a load register Instruction. The accumulator Is 
scrambled. 

WNDB - Set Window Bottom 

LAB WNDB NUM 

LAB - label 
NUM - number 

The screen window’s bottom margin Is set to NUM. NUM must be a valid operand for a 
LDA instruction. NUM must be lessthan or equaltotwenty-fourand greaterthanzero. It 
must also be greater than WNDT. Note that the bottom margin Is the line numberof the 
bottom line to be used plus one. The accumulator is scrambled. 

WNDL - Set Window Left 

LAB WNDL NUM 

LAB - label 
NUM - number 

The screen window’s left margin is set to NUM. NUM must be a valid operand fora LDA 
instruction. WNDL + WNDW must be less than forty. The accumulator is scrambled. 

WNDT - Set Window Top 

LAB WNDT NUM 

LAB - label 
NUM - number 

The screen window’s top margin is set to NUM. NUM must be a valid operand fora LDA 
instruction. It can range from zero to thirty-nine, but must be less than WNDB. The 
accumulator Is scrambled. 
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WNDW WRITE WRITEC 


WNDW - Set Window Width 

LAB WNDW NUM 

LAB - label 
NUM - number 

The screen window’s width is set to NUM. NUM must be a valid operand for a LDA 
instruction. WNDL + WNDW must be less than forty. The accumulator is scrambled. 

WRITE - Write Characters with Return 

LAB WRITE CHRS,NUM 

LAB - label 

CHRS - address of characters to print 
NUM - number of characters to print 

Write the characters pointed to by CHRS on the current output device, followed by a 
return. NUM is the optional number of characters to print. If not included, the length 
attribute of the label Is used. All registers are scrambled. 

WRITEC - Write Centered Characters with Return 

LAB WRITEC CHRS,NUM 

LAB - label 

CHRS - address of characters to print 
NUM - number of characters to print 

Write the characters pointed to by CHRS on the current output device, followed by a 
return. The characters are preceded with enough blanks to center them on a forty 
column screen. NUM Is the optional number of characters to print, and must be less 
than thirty-nine. If not included, the length attribute of the label Is used. All registers are 
scrambled. 
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WRITE2 


WRITE2 - Write Characters Without Return 
LAB WRITE2 CHRS^NUM 
LAB - label 

CHRS - address of characters to print 
NUM - number of characters to print 

Write the characters pointed to by CHRS on the current output device, without a return. 
NUM is the optional number of characters to print. If not included, the length attribute of 
the label is used. All registers are scrambled. 
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Low Resolution Graphics 

This section describes macros which allow access to low resolution graphics. Most of 
the commands available in BASIC have a counterpart here. These routines use 
subroutines present in the monitor ROM, so they do not depend on the subroutine 
library. The macros are contained in MACLIB.GR. 

CLRGR - Clear Low Resolution Graphics Page 

LAB CLRGR ALL 

LAB - label 

ALL - flag indicating amount of screen to clear 

If ALL is not coded, the top forty rows of the low resolution screen are cleared to black. If 
ALL is coded, all forty-eight rows are cleared. In the text mode, the screen is filled with 
inverse @’s. The contents of A and Y are scrambled. 


COLOR - Set Low Resolution Plot Color 

LAB COLOR C 

LAB - label 
C - color 

Sets the low resolution plot color to C. C may be any valid operand for a LDA 
instruction, or it can be the color name listed in column three below. Values of C and 
their corresponding colors are: 

Value Color Operand Name 


0 

black 

BLACK 

1 

magenta 

MAGENTA 

2 

dark blue 

DBLUE 

3 

purple 

PURPLE 

4 

dark green 

DGREEN 

5 

grey 

GREY 

6 

mediumblue 

MBLUE 

7 

light blue 

LBLUE 

8 

brown 

BROWN 

9 

orange 

ORANGE 

10 

grey 

GREY 

11 

pink 

PINK 

12 

green 

GREEN 

13 

yellow 

YELLOW 

14 

aqua 

AQUA 

15 

white 

WHITE 
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GR GREAD HLINE 


GR - Display Low Resolution Graphics 
LAB GR ALL 
LAB - label 

ALL - indicates split page or full page 

The screen mode is switched to low resolution graphics. If ALL is coded, the entire 
screen is dedicated to graphics. If ALL Is not coded, the top part of the screen is 
dedicated to graphics, while the bottom four lines are still used for text. Note that the 
screen is not cleared. 

GREAD - Read the Color of the Low Resolution Screen 
LAB GREAD X,Y 
LAB - label 

X - horizontal position 

Y - vertical position 

The color of a low resolution graphics block Is placed In the accumulator. X is the 
horizontal position, from zero to thirty-nine. Y is the vertical position, from zero to forty- 
seven. Y is measured with zero at the top and forty-seven at the bottom. Both X and Y 
must be valid operands for a load register instruction. 

HLINE - Draw Horizontal Line 

LAB HLINE X1,X2,Y 

LAB - label 

XI - lowest X 
X2 - highest x 

Y - y coordinate 

A horizontal line of the current color Is drawn from XI to X2 at constant Y on the low 
resolution graphics screen. XI, X2 and Y must be valid operands for load instructions. 
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PLOT VLINE 


PLOT - Plot a Low Resolution Point 

LAB PLOT X,Y 
LAB - label 

X - horizontal position 
Y - vertical position 


A single low resolution graphics block is plotted. X is the horizontal position, from zero 
to thirty-nine. Y is measured with zero at the top, going to forty-seven at the bottom of 
the screen. Both X and Y must be valid operands for a load register instruction. The 
color must have been set previously. 


VLINE - Draw a Vertical Line 


LAB VLINE X,Y1,Y2 

LAB - label 
X - X coordinate 
Yl - lowest y 
Y3 - highest y 


A vertical line of the current color Is drawn at constant X from Yl to Y2. X, Yl and Y2 
must be valid operands for load Instructions. 
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High Resolution Graphics 

These macros provide equivalents to most of the BASIC high resolution graphics 
commands. Shape commands have deliberately been avoided both because they are 
tape based and because it is faster and more direct to build a shape using binary DC 
statements and transfer the result to the high resolution screen. The macros are 
contained in MACLIB.GR, and require Applesoft in ROM to work. 

HCLEAR - Clear the High Resolution Screen 

LAB HCLEAR 

LAB - label 

The current high resolution screen is cleared to black. 

HCOLOR - Set High Resolution Color 

LAB HCOLOR C 

LAB - label 
C - color 

Sets the high resolution color to C. C must be X, a valid operand for a LDX instruction, 
or the color name. The valid range is zero to seven. The high resolution colors are listed 
below. 

Color 
Number 

0 
1 
2 

3 

4 

5 

6 
7 


Color 

BLACK 

GREEN 

VIOLET 

WHITE 

BLACK2 

ORANGE 

BLUE 

WHITE2 
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HDRAW HGR 


HPAGE 


HDRAW - Draw a High Resolution Line 
LAB HDRAW X,Y 
LAB - label 

X - X coordinate to draw to 
Y - y coordinate to draw to 

A line is drawn from the current cursor to X, Y. X should be the address of a two byte 
positive Integer. Y should point to the one byte y-coordinate, increasing from the top to 
the bottom of the screen. Both X and Y must be valid operands for load instructions. 

HGR - Display High Resolution Graphics 

LAB HGR ALL 

LAB - label 

ALL - full page flag 

Sets graphicsand high resolution switches for pageone high resolution graphics. If any 
character is coded in the operand, full page graphics result; otherwise a split screen 
with four lines of text is generated. 

HPAGE - Set the Page to Draw On 

LAB HPAGE PAGE 

LAB - label 

PAGE - page to draw on 

Sets the page that the high resolution graphics routines will draw on, regardless of the 
page being displayed. PAGE should be 1 or 2, and must be set before plotting 
commands will work correctly. 
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HPLOT HPOSN 


HPLOT - Plot a High Resolution Point 
LAB HPLOT X,Y 
LAB - label 

X - x-coordinate to plot 

Y - y-coordinate to plot 

A high resolution point ofthecurrentcolor is plotted at X,Y. X should point to atwo byte 
number, while Y points to a one byte number. Both X and Y must be valid operands for 
load Instructions. 

HPOSN - Position the Cursor 

LAB HPOSN X,Y 

LAB - label 
X - X coordinate 

Y - y coordinate 

Position the high resolution cursor to X, Y. X should point to atwo byte positive value for 
the X coordinate. Y should point to a one byte y-coordinate, increasing from the top to 
the bottom of the screen. Both X and Y must be valid operands for load instructions. 
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Miscellaneous Macros 

This section includes various macros used for interfacing with monitor subroutines and 
special memory locations. They do not require use of the subroutine library or a 
particular monitor ROM version. They are contained in the file MACLIB.MSC. 

BELL - Sound Apple Bell 

LAB BELL 

LAB - label 

Calls the Apple monitor subroutine which beeps the speaker. 

BUTON - Read a Button 

LAB BUTON BTN,VAL 

LAB - label 

BTN - button to read 

VAL - value of button 

The value of the button BTN is placed in VAL. BTN should be In the range zero to two, 
and must be a valid operand for a LDX instruction. If missing, the X register is assumed 
to have the button number in it. The result is stored In VAL If VAL is coded, and is also in 
the accumulator. If bit seven Is zero, the button was not being pressed at the time the 
sample was taken; if It Is one, the button was pressed at that time. 

PAGE1 - Set Page One 

LAB PAGEl 

LAB - label 

Sets the display to text page one. 

PAGE2 - Set Page Two 
LAB PAGE3 
LAB - label 


Sets the display to text page two. 
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DW 


LA 


LM 


DW - Define Word 

LAB DW ‘AD» 

LAB - label 

ADR - word to define 

The character string ADR is defined as a DC statement of type character, preceded by a 
one byte integer which is the number of characters in the string. This allows tables of 
strings to be built. The table can be stepped through by adding the length of the string 
plus one to its address to get the location of thestart of the next string. ADR need not be 
enclosed in quote marks if it does not contain blanks, commas or equal signs, and if it 
does not start with a single quote mark or left parentheses. If any of these characters 
appear, the string must be enclosed In quote marks. Quote marks enclosed in quote 
marks must be coded as four quote marks. 

LA - Load Address 

LAB LA AD1,AD2,R 

LAB - label 

ADI - location to put address In 
AD2 - address to put In ADI 
R - register to use 

The address of AD2 Is placed at ADI, least significant byte first. R is the register to use, 
and is optional. It defaults to A. ADI may be specified as a multiple operand. 

LM - Load Memory 

LAB LM AD1,AD2,R 

LAB - label 

ADI - location to load to 
AD2 - value to load 
R - register to use 

AD2 must be a valid operand for a load register instruction. It Is loaded Into a register 
and stored at location ADI, which must be a valid operand for a store register 
instruction. ADI can be a multiple operand. If R Is coded, it Is the register to use. If R is 
not coded, the accumulator Is used. 
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MOVE PREAD _RESTORE 


MOVE - Move Code 

LAB MOVE AD1,AD2,L,R 
LAB - label 

ADI - address to move from 
AD2 - address to move to 
L - length of move 
R - index register 

L bytes are moved from location ADI to location AD2, working from the end. L is 
optional, and defaults to two if omitted. L must be a valid operand for a load register 
instruction, and must be in the range 0 to 255. If 0, 256 bytes will be moved. R is the 
register to be used for indexing, and defaults to X if omitted. AD2 may be specified as a 
multiple operand. ADI may be an Immediate operand, in which case the immediate 
value is moved to each target location. 

PREAD - Read a Paddle 

LAB PREAD PDL,VAL 

LAB - label 

PDL - paddle to read 

VAL - value of paddle 

The paddle PDL Is read, and its value placed in VAL. PDL must be a valid operand for a 
LDX instruction. Its range is zero to three. If missing, the current value of the X register is 
used. VAL must be a valid operand for a STY instruction. The value of the paddle is left In 
Y. 

RESTORE - Restore Registers 
LAB RESTORE 
LAB - label 


The user registers are restored from the stack in the order X, Y, A. 



THE LIBRARIES 


149 


SAVE TEXT 


WAIT 


SAVE - Save Registers 
LAB SAVE 
LAB - label 

The user registers are saved on the stack in the order A, Y, X. 

TEXT - Display Text 
LAB TEXT 
LAB - label 

Set the CRT display mode to display text. 

WAIT - Pause for a While 

LAB WAIT CNT 

LAB - label 
CNT - wait count 

Calls the monitor wait subroutine. If CNT is not specified, the longest wait possible is 
used. If CNT is A, the routine is called with that value; otherwise CNT must be a valid 
operand for a LDA instruction. The pause will be .5 * (26 + 27 * CNT + 5 * CNT ♦ CNT) 
microseconds long. 
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Chapter Seven 
The Style Manual 

About the Style Manual 


Strictly speaking, a style manual is a set of dogmatic principles one follows In order to 
create standardized code. This helps one programmer to more easily understand the 
work of another, and gives beginners guidelines on how best to use the language. This 
chapter will attempt to fulfill this purpose, and also show how the system was Intended 
to be used. The hope is that if the user understands some of the “why” behind the 
system, it will allow working with the system rather than against it. 


Assembly Language Files 


This section lays out a standard format for assembler language source files. There are 
sure to be applications where some of this advice does not apply. However, if there Is no 
good reason for not following the advice, it is suggested that these guidelines be 
followed; they will generally help avoid trouble later on. 

The Source Line 

Source lines include 6502 instructions, macros and assembler directives. All of these 
lines have standard fields, which were explained In chapter four. These fields, from left 
to right, are the label, operation code, operand, and comment field. The text editor has 
default tab stops set in columns eight, fourteen, and twenty-one. These columns define 
the standard starting place for each of these fields. 

Users familiar with high level languages, especially block structured languages like 
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Pascal or Algol, may have a tendency to indent in assembler. This tendency is best 
avoided. The reason for indenting is to clarify program structure; this usually does not 
work In assembler language. Instead, structure is Indicated by leaving blank lines to 
divide logical sections of code from one another. Block comments are also used, as 
detailed below. 

Commenting Programs 

Good comments are important In any language; they are critical In assembler language. 
Any time spent In typing comments will be repaid many times over when it comes time 
to debug the program. This will again be true If a decision is made to add a new feature 
to a program that has been gathering dust for a few months. 

Comments on the line are generally very helpful, but do not insist on a comment on 
every line. If there Is nothing to say, say nothing! In particular, do not place comments 
on a line which say the same thing as the instruction: 

LDA #BLACK LOAD ACCUMULATOR WITH BLACK 

It would be much more sensible, not to mention useful, to see: 

LDA ^LACK CHECK FOR BLACK PIECES 

Comments frequently extend over more than one line. When this happens, Indent the 
succeeding lines of the comment one space so that it is clear that the comment Is more 
than one line long, rather than having several lines with short comments. An example 
from the operating system shows how this is done. 

CMP #0 RETURN TO APPLE IF 

JEQ APPLE RETURN CODE IS 0 

Especially when macros or assembler directives are used, the operand field will 
occasionally extend past column twenty. If a comment is needed on the same line, skip 
one space and begin the comment Immediately. If the comment extends to another line, 
start the next comment line one space to the right of the original comment, even If it 
could have started several spaces sooner. The resulting multi line comments are still 
easier to read than a comment which starts in random columns. 

Finally, be sure and stick to fifty-nine columnsforassembler files. Otherwise, theoutput 
cannot be printed properly on an eighty-column printer. The eighty columns provided 
in the editor will be useful If compilers for high-level languages are used with the 
system. 

Each subroutine and data area should begin with a block of comments which are 
distinctively set apart from the code. As can be seen from the listings In the appendices. 
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this can be done by surrounding the block of comments with asterisks. This block of 
comments, at a minimum, should contain the subroutine name, a short title for the 
subroutine, and detailed lists of all inputs and outputs. If the short title is not adequate 
by Itself, a description of the purposeand useof thesubroutineshould also be included. 
Another section which Is sometimes useful is a “notes” section. This section should be 
used to document strange features, such as alternate entry points. Sources for other 
documentation, such as magazine articles, could also be documented here. 

Subroutines should be divided into main logical subsections by block comments. This 
block comment should describe what the section of code does at an overview level. 
Exactly how the function is performed can be left to comments on the lines themselves. 
The various comment identifiers may be useful in setting blocks of code apart from one 
another. Examples from the system listings show the use of three lines starting with 
semicolons, with the center line containing the comment. If there are enough block 
comments that a hierarchy is needed among them, outline the comment in semicolons 
on the left and right and periods on the top and bottom. 

If there seems to be a need for more structure than can be provided by two hierarchies of 
comments, the subroutines are probably getting too long. A rule ofthumb for managing 
subroutine length is to keep it short enough that the entire subroutine can be looked at 
all at once. This usually translates to meaning thata subroutine with all of its comments 
should be no longer than two pages. If It is longer than this, it probably contains more 
than one main idea. This makes the subroutine hard to read for two reasons: the 
collection of ideas can get intertwined and confused, and the subroutine must be 
examined in pieces. Another way to judge whereto break subroutines istothinkofthem 
as serving the same logical function as a paragraph; a subroutine should contain one 
and only one main idea. 

There is one more type of comment line Intended for programmer use. It begins with an 
exclamation point. This should be reserved for continued comments. This may be 
necessary if a comment must exceed one line in length, yet the next line of code also 
needs a comment. 

Label Conventions and Use 

Two types of labels need to be discussed. The first are those defined by a DC or DS 
directive. These are typically used to identify memory areas used for storage of tables, 
character strings and numeric data. 

For clarity, these definitions should be collected in one part of the subroutine. Placing 
then at the beginning, as would be done In a high level language, would require a jump 
around the variables being defined. To avoid this jump, it is customary to place variables 
at the end of a subroutine. 

Another consideration is the separation of labels used within a single subroutine from 
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those used by several subroutines. The DATA area is intended to handle common use 
variables. The tendency to place all variables in a single data area should be resisted. 
Data areas, like subroutines, should be kept as short as possible. Tables and variables 
used by only one subroutine should be placed in that subroutine, not in a DATA area. 

The second main type of label istheassemblerconstant.Theconstanttakestheform of 
an equate, and Is used to define locations in memory and to assign names to numbers 
whose meaning might otherwise be confusing. Forexample, a chess program might use 
the most significant bit to mark color, sothat white was represented by $00 and black by 
$80. Instead of using these values, the values should be assigned to the names WHITE 
and BLACK, and these names used in the program itself. 

Like memory variables and constants defined by DC and DS directives, assembler 
constants should be collected in a handy place In the subroutine. Since zero page 
constants must be declared before use, it is a good idea to declare all constants at the 
top of the subroutine. USING statements should also be placed at the top, usually 
before the constants. Also note that data areas may contain constants. This can be very 
convenient, since a constant used in several subroutines will need to be changed in only 
one place if a change becomes necessary. 

Zero page labels that will be used by more than one subroutine present a special 
problem. If included in data areas, the subroutines must be told that the label is zero 
page when used in a subroutine. At best, this Is inconvenient. It would still be nice to be 
able to define common zero page variables In a single location. This can be done with 
the global equate statement. A constant declared before its first use becomes available 
to all succeeding subroutines at assembly time. This is handled differently than other 
types of global variables, which are left to the link editor for resolution. Recall that if a 
few subroutines are specified for assembly from a larger source file, the source file Is 
scanned for some types of source statements which have global meaning. These are 
resolved, even if they appear inside a subroutine which is not being assembled. The 
global equate Is one of these statements, allowing for resolution of zero page constants. 

One last topic is label naming conventions used as branch points orsubroutine names. 
As much as possible, these variables should be given meaningful names. This can help 
future understanding of a subroutine almost as much as comments. 

Also note that labels defined within macros in the macro library all have a standard 
format. They start with SYS, followed by a second alphabetic character, and end with 
zero to five numeric characters. This may cause a duplicate label error if labels of the 
same format are used, so try and avoid them. 

Finally, subroutines in the subroutine library are named so that each subroutine name 
starts with SYS, and is generally followed by four characters. 
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Macros and Macro Libraries 


The strength of a macro assembler is the ability of the assembler to define custom 
instructions to generate common sequences of instructions. For example, a two byte 
integer add takes seven instructions on the 6502. The macro library allows the coding of 
a single Instruction Instead of the normal seven. This reduces the time required to write 
a program, since fewer lines need be written. It also reduces the chances of a mistake. 
The code that results Is easier to read, and hence program maintenance becomes 
easier. 

Unfortunately, there Is no free lunch. The assembler is doing far more work than one 
that cannot resolve macros, hence it takes longer. Macro libraries must be maintained, 
and there Is the nagging possibility that a macro might actually contain a mistake. Such 
a mistake will not be evident unless the GEN ON option is used, which In turn makesthe 
assembler listing difficult to read. 

All of this points out the need for careful management of macro libraries. When new 
macros are created. It Is essential that the macro be tested very thoroughly. The best 
way to do this is to write a short program which contains nothing but the new macro. 
The goal is to code the macro in enough ways that each line in the macro definition is 
executed at least once during the expansions. Each conditional branch should be 
tested by causing the branch to be executed with both true and false conditions. The 
GEN ON option must be used, and the resulting output examined to insure that It is 
exactly as desired. Only then should the new macro be included in a library. 

In general, macros should not be expanded In the source listing of a program. The first 
exception is if library macros generated by another programmer are being used, and the 
user wants to see what they do. Another exception is If a particular macro is suspected 
of containing an error; here the macro expansion should be turned back off after the 
suspected macro is expanded. Finally, If assembler language programs which Include 
source listings are being published for an audiencethat may not befortunateenough to 
have a macro assembler, two listings should be provided. One listing should be normal, 
the other should have the macros expanded. The normal listing allows easy reading of 
the program, while the expanded listing lets people without macro assemblers enter the 
source code. A brief description of each macro should also be included. 


Speeding up Assemblies 


Proper management of the assembler can speed up assembly time by amazing 
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amounts. Once these techniques become familiar, they will become fairly automatic. 
For the effort of learning these rules, assemblies will occur several times faster than if 
the rules were not followed. 

Virtually all of the tips for speeding up assemblies center around reducing disk 
accesses to a minimum. This means that source files should be as long as possible, and 
all files needed by a program should be crammed on as few disks as possible. If the 
program Is long enough to require disk swapping, keep a close eye on how the disks are 
requested. This can give valuable information on how to arrange files on the disks to 
minimize the swaps needed. 

Perhaps the best way to speed up assemblies is proper management of macro libraries. 
Once a macro library is in memory, the time required to locate a macro In the library Is 
minimal. If more than one macro file Is used, swapping of the files can cause exorbitant 
amounts of disk access. For this reason, each program should have its own file of 
macros. Only those macros used by the program should be included. If more than one 
macro file is needed, the first file should contain the most frequently used macros, 
followed by the next most frequently used in the second file, and so on. Also consider 
the possibility of using different macro files for different sections of the program. All of 
the I/O routines could be grouped together, and I/O macros be placed in one file for 
them. Another section might contain all of the math routines, with math macros being 
placed in a file for those subroutines. 

Another tactic is to help the assembler find macros. This Is usually not necessary unless 
several macro files are being used. In that case, a subroutine which uses floating point 
math macros might start with an MLOAD statement to load the needed macros into 
memory. This prevents the assembler from searching the libraries In order, since the 
proper library Is in memory when it looks for the macro to expand. 

Keeping subroutines short helps the assembler almost as much as the programmer. 
The assembler has less overhead on short subroutines; symbol tables are shorter, 
requiring less time to construct and search. This Is especially true if the object modules 
created by the assembler are larger than the code build area (2K for48K systems, 4K for 
64K). This is usually the cause If the assembler starts doing disk accesses on virtually 
every line. The assembler will handletheobject module correctly, but it will takea much 
longer time than if the subroutines are shortened. 

This may sound unduly restrictive, but it really isn’t. Remember that DS statements at 
the end of a subroutinedon’ttake up room In the object module. In practice, a300to400 
line subroutine will fit into a2K buffer. This length is of course doubled for64K systems. 
Even a 300 line subroutine is too long to read easily; if the advicegiven earlier is heeded 
about the structuring of programs, one should never see a subroutine that long. 

Finally, If listings of the source code and symbol tables are not needed, turn them off. It 
takes time to print them, sometimes as much as ten to fifteen per cent of the total time 
spent on the assembly. Turning off the listings and symbol tables also helps scan for 
errors. Not only are error lines the only ones listed, they are the only output lines that 



THE STYLE MANUAL 


157 


will stop the assembler if a key is pressed. This allows an assembly to be started and a 
key pressed. The assembler will stop on the first error line. A flashing cursor will 
Indicate that an error line is ready for listing. Pressing any key causes it to be listed. A 
key may then be pressed again to wait for the next error, or ESC could be pressed to 
jump to the line in the source file for editing. 


Partial Assemblies 


One of the nicest features of a link editor is that it can combine object modules, using 
the most recent versions of duplicate subroutines. The assembler provides the 
capability of assembling a selected few subroutines In a source file. For example, if a 
20,000 line program took thirty minutes to assemble, but the last subroutine had an 
error, it is not neccesary to reassemble the entire program. Simply make the 
corrections, and reassemble the offending subroutine. The link editor then combines 
the old and the new, selecting the most recent version of each subroutine. 

At times, reassembly of the entire program is necessary. This generally happens 
because one of the directives that effect the entire assembly is changed, like a GEQU. 
(See page 000 for a complete list of these directives.) The program also needs to be 
reassembled if twenty-five partial assemblies have been done, resulting in files with 
every letter of the alphabet as suffixes to the root name. Another reason Is if the multiple 
copies of subroutines are taking up enough room that the disk becomes crowded. 
Finally, the entire program must be reassembled if the order of the subroutines is 
critical, or if a subroutine Is deleted from the program. 

In any of these cases, the root file and all partial assembly files must be deleted before 
assembling the entire program. For example. If four partial assemblies of the program 
MYFILE have been done, the disk will contain the object modules: 

MYFILE.ROOT 
MYFILE.A 
MYFILE.B 
MYFILE.C 
MYFILE.D 
MYFILE.E 

To delete all of these files, type 


D MYFILE = 

from the monitor. Prompting can be used if other files that start with the characters 
MYFILE are on the same disk. 

Chapter four describes the parameters needed to do partial assemblies. 
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Appendix A 
Error Messages 


Introduction 

During assembly and link editing the system attempts to identify coding errors in the 
source file. These errors fall Into two broad categories; those that can be recovered 
from, and those that cannot. 

Recoverable Assembler Errors 

When an error is encountered by the assembler, it is flagged in the output source listing. 
The error message includes a brief description of the error; more detailed descriptions 
are listed below. Severity levels are also listed for the various errors. This is shown In 
square brackets after the error message. 

The error severity codes are divided as follows: 

Severity Meaning 

8 Warning - things may be OK 

4 Error - an attempt at correction was made 

8 Error - no correction is possible, but only this instruction was 

effected. Space is left for correcting the program using the Apple 
monitor. 

16 Error - It was not possible to tell how much space to leave. 

Reassembly Is mandatory. 

At the end of the source listing, the number of errors encountered Is listed, as well as the 
maximum severity level detected. 

ACTR Count Exceeded [16] 

More conditional assembly branches have been encountered in a single macro 
resolution than allowed. An infinite loop is suspected. Further resolution of the macro Is 
suspended. 
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Check the conditional assembly Instructions for a possible infinite loop. If there Is a 
valid reason to make more than 255 conditional assembly branches, insert an ACTR 
statement In the source file to prevent this error. 

Addressing Error [16] 

The location counter from pass two did not match the value of the label as stored during 
pass one. 

Check for zero page addresses that were not resolved when this line was encountered 
on the first pass. (All zero page addresses must bedefined before their first use.) Check 
labels used in AIF statements to Insure that they had the same value on all passes. 
Check math operations to insure that thevaluewould not havechangedfromzero page 
to non zero page (or non zero page to zero page) as the result of resolving a label. 
(Labels which are not yet resolved are assigned the value $8000 during pass one.) 
Check for duplicate labels used In the operand. 

DC too Large [16] 

The DC statement tried to generate more than 256 bytes of code. 

Break the DC statement up Into several smaller statements. 

Duplicate Label [4] 

The same label has been encountered more than one time in a program segment; or 
more than one global label is the same; ora local label and global label are the same; ora 
macro definition contains duplicate symbolic parameters; orasymbolic parameter was 
redefined. The value of the first label found is used, subsequent repetitions are Ignored. 
No more than ten duplicate labels are flagged In a single assembly segment. For 
duplicate sumbolic parameters In a macro definition statement, macro resolution Is 
terminated. 

Change one of the labels so that the duplication does not occur. 

Note that for duplicate symbolic parameters in a macro definition statement, the macro 
call statement receives the error message - the macro definition statement Is not listed. 

Duplicate Reference in MACRO Operand [2] 

The macro call referenced the same symbolic parameter more than one time. The 
macro expansion is suspended. 

Check to insure that two keyword parameters do not use the same keyword. Insure that 
keyword parameters do not set a symbolic parameter that is also set by a positional 
parameter. 
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Expression Too Complex [8] 

The expression in the operand contains more than one type of update which must be 
resolved by the link editor. This results from an attempt to use more than one label that 
was not defined by an EQU or a GEQU in the same line. Note that this restriction does 
not apply to subtractions of local labels, although this can cause an error which is not 
detected if a PAGE or ORG directive is used between the labels that were subtracted. 

Eliminate all but one of the labels that were not defined by an EQU or GEQU. 

Invalid Oper on Global Label [4]] 

The operand contains a global label that could not be resolved as a label plus some 
predetermined constant. Offending operations are ignored in the operand. 

An operand can contain only oneglobal label. If it has morethan one, remove the extras. 
Only adds and subtracts can be made to a global label. Remove any other operations. 

Invalid Operand [8] 

The operand type is not valid for the operation code; ora label appears in an operand or 
directive that is not contained in a subroutine. Free space is left based on the operand 
type. 

Check appendix B to insure that the operand type is valid for the operation. If it is, review 
the syntax of the operand for coding errors that might have confused the assembler. 
Insure that A was not used as a label. If the operand contains a label ( * is considered a 
label). Insure that it is inside a subroutine. If the NAMES= assembler option is being 
used. Insure that the subroutine is assembled. 

Label Syntax [16] 

Either a field that was believed to be a label did not conform to the standard label syntax 
rules or a label was used when a symbolic parameter was expected. Free space is left 
based on the operand type. 

If the problem is with a label, check it against the label syntax rules of chapter four, 
section two. Insure that sequence symbols begin with an & character. Check forsyntax 
errors which may have confused the assembler. 

Length Exceeded [4] 

The valid length of some numeric value was too large. Free space Is left based on the 
operand type. 

Check the description of the statement for valid operand ranges. 
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MACRO Operand Syntax Error [4] 

The operand of the macro definition statement does not conform to standard coding 
rules. Expansion of the macro is suspended. 

Check the macro definition for errors in the macro definition statement. 

Misplaced KEEP [16] 

Either more than one KEEP statement was used or the KEEP statement appeared after 
the first START statement. 

Remove extra KEEP statements. The KEEP statement should be the first statement in 
the program (or the second if the first is a PRNT ON ). 

Missing Operand [16] 

The operand field was expected but not found. The instruction is ignored. 

Insure that the operand starts before column twenty-one. If the operation extends past 
column eighteen, insure that there is no more than one blank between It and the 
operand. 

Missing Operation [16] 

The operation code field was not occupied. The instruction is Ignored. 

Insure that the operation code begins before column twenty-one. Insure that the label 
starts in column one. 

Nest Level Exceeded [8] 

Either macro definitions contained other macro definitions to a level more than four 
levels deep, or an arithmetic expression caused a stack error during evaluation. The 
statement Is Ignored. 

Insure that a macro does not call itself or another macro that calls itself. Check 
arithmetic Instructions for mismatched parentheses, more than one math operation not 
separated by an operand, more than one operand not separated by a math or logical 
operation, and syntax errors In labels and expressions. Insure that arithmetic 
expressions do not contain blanks. This error can also occur if the math evaluation 
routine cannot find enough room in the symbol table or if an expression has more than 
forty-two operands and operations. 
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No END [2] 

A subroutine or data file had no END statement. This can also cause the symbol table to 
overflow or duplicate labels to be found. No action is taken. 

Place an END statement at the end of the subroutine or data file. Insure that the last 
statement in the source stream is an END statement. 

Number Overflow [4] 

Resolution of a floating point number has resulted in an exponent outside of allowed 
ranges. The least significant bits of the exponent are used. 

Single precision numbers can range from about IE-38 to 1E+38. Double precision 
numbers can range from about 1E-9864 to 1E+9864. Insure that the number is in these 
ranges. 

Numeric Error in Operand [8] 

Either an arithmetic operation was performed which resulted in an overflow or a division 
by zero was attempted. Free space is left based on the operand type. 

Change the operand so that the errordoes not occur. Check all labelsto Insure that they 
contain the expected values. 

Operand Syntax [16] 

The operand field did not correspond to standard coding rules. Free space Is left based 
on the operand type. (No space is left for a DC statement.) 

Check the section dealing with the instruction for syntax conventions. 

Operand too Big [2] 

An operand for a directive that expected a one byte number contained a number greater 
than 255. The number modulo 256 is used. 

Check to Insure that all labels contain the expected values. 

Rei Branch Out of Range [8] 

An attempt was made to use relative addressing when the branch point was outside of 
the range of relative addressing. The valid range Is -125 to +129 bytes from the 
beginning of the instruction. Two free bytes are left. 

Use a branch around a JMP Instruction or one of the jump macros to extend the range of 
the branch. A branch to an undefined label will also give this error. 
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Repeat Count > 255 [16] 

An attempt was made to repeat a DC operand more than 255 times. Resolution of the DC 
statement is suspended. 

Lower the repeat count. 

Sequence Symbol Not Found [4] 

A sequence symbol could not be located In a valid rangeof thesourcefile. No branch is 
made. 

Check to insure that the sequence symbol is coded properly. Make sure that It is in the 
same source file as the branch. If the branch is in a macro, insure that the sequence 
symbol is between the MACRO and MEND statements that surround the branch. Check 
for spelling errors and unwanted blanks in the sequence symbol. 

Set Symbol Type Mismatch [4] 

Aset symbol did not match the type of the symbolic parameter it was to modify. The line 
is ignored. 

Check the type of thesymbollc parameter. Comparethis with thetypethat chapterfour, 
section four lists as valid. 

Subscript Exceeded [8] 

A subscript reference that was too large was made to a symbolic parameter. 

Check the number of subscripts defined for the symbolic parameter. Check labels and 
symbolic parameters used to define the subscript to insure that they have the expected 
values. Note that zero subscripts are not allowed, and will result in this error. 

Subscript Out of Range [4] 

A subscript used to define a symbolic parameter was not in the range 1 to 255. 

Check to insure that any labels or symbolic parameters used In the definition have the 
expected value. 

Too Many Giobal Labeis in DC [8] 

The DC statement references more that six global labels. 

Reduce the number of global labels in the DC statement to six or fewer. This can be 
done by breaking the DC statement up Into two or more smaller DC statements. 
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Too Many MACRO Libs [2] 

An attempt was made to activate more that eight macro libraries. Subsequent attempts 
are ignored. 

Drop unneeded libraries before activating the new one. These can be restored later 
when some other library is no longer needed. Try eliminating unused macros and 
combining small libraries. 

Too Many Positional Parameters [4] 

A macro call contained more positional parameters than the macro definition. 
Resolution of further positional parameters Is suspended. 

Check for extra commas or keyword references in the wrong place. 

Undefined Symbolic Parameter [8] 

A symbolic parameter was referenced but not defined. The line is ignored. 

Check for spelling errors or errors in the symbol definition line. 

Unidentified Operation [16] 

The operation code did not match any instruction, assembler directive, or macro. The 
line Is ignored. 

Check to insure that macro names are less than eleven characters long. Insure that all 
needed macro files were active. Check for label syntax errors which may have confused 
the assembler. Note that any label defined by this statement is not placed in the symbol 
table, and will be unresolved. 

Unresolved Ref in Equate [2] 

The equate referenced a label that was not resolved at the time of assembly. The link 
editor may not be able to properly relocate uses of the equate In the subroutine. 

If possible, remove the offending equate, or place the unresolved label earlier in the 
program and define it with a GEQU directive. If the value of the equate is correct. 
Include the statement 

MERR 2 

at the beginning of the program to allow automatic link editing and execution of the 
program even though the error still exists. 
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Terminal Assembler Errors 

The following errors cause the assembler to terminate processing. After printing the 
error message and waiting for a key press, the operating system loads the monitor and 
enters the editor with the offending statement on the top line of the display window. 

Catalog Full 

An attempt was made to save a new file on a disk whose catalog was full. 

Spread the program over more disks. So long as volume parameters are used, there Is 
no limit to the number of disks that the assembler can access. 

Copy Level Exceeded 

An attempt was made to copy more than four levels deep. 

Check for files that may copy themselves. 

Disk Full 

A sector was needed to save something on the disk, but there was no more room. 

Spread the program over more disks. There is no limit to the number of disks that the 
assembler will use. 

Drive Error 

The RWTS subroutine has returned an error code of $40. This indicates a drive error. 

Check for a damaged disk. Place the file that was being accessed on a different disk. 
Check the VTOC for the file being loaded to insure that ail of the sectors reserved have 
valid track and sector numbers. 

File Not Found 

An attempt was made to load a file which was not on the specified volume. 

If some volume numbers have been specified, but not for this file, include a volume 
parameter. Check the file name for spelling and insure that the disk file name contains 
no hidden characters. 

File Type Mismatch 

A file did not have the file type S. 

Check to insure that no files have duplicate names with files of another type. 


ERROR MESSAGES 


167 


Keep File Locked 

The file name given for saving code already exists, and is locked. 

Unlock the file if it is no longer needed, or change the name of the keep file. 

Missing START 

An instruction or directive which must be placed inside a program segment was 
encountered after and END statement and before a START statement. 

Review the organization of the subroutine. All statements which generate code, set up 
local labels or use labels in their operand must appear between the START and END 
statements. 

Read Error 

The RWTS subroutine was unable to read a disk sector. 

Check for a bad disk or sector. Move the file to a different disk. 

Source File Too Long 
A source or macro file was longer than 8K. 

Shorten the offending file, using COPY or APEND directives to connect the shorter 
files. If the source file was longer that 16K, or If the offending file was a macro file, reboot 
the system before proceeding. 

Write Protected 

An attempt was made to write to a write protected disk. 

Change the volume number on the keep file to a volume that is not write protected. 
Insure that the volume with the assembler on it is not write protected. 


Recoverable Link Editor Errors 

These errors may occur at link edit time. As with assembler errors, they have an 
associated error level. These levels have been assigned the same significance as they 
were with the assembler errors. 

Backward Ref by ORG at $XXXX [8] 

An ORG directive was issued for a memory location that has already been passed. 
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If possible, remove the ORG from the source file. Also, check to see if the link editor is 
putting the subroutines in the order expected. (When doing partial assemblies of a few 
subroutines, the order can change. This can be corrected by re-assembling the entire 
program.) 

Data Area Not Found [2] 

A data area was referenced but not found. 

If the data area is in asubroutine library, insurethat all subroutine libraries are available 
and on the same disk. If not, the program must be corrected to either provide the label, 
or not reference it. 

Duplicate Label [8] 

Two global labels of the same name have been defined. This is the second one. 

Remove or rename one of the labels. Renaming a label can only be done by re¬ 
assembly. Removal of a label may occasionally be possible if the label is In a subroutine 
library for which there is an alternate library with different names. 

Memory Reserved Too Late [16] 

An attempt was made to reserve memory after the start of the memory to be reserved 
had been passed. The request Is ignored. 

Make the request sooner in the program. Checkto Insure thatsubroutines are being link 
edited in the order expected. If not, reassemble the program in the desired order. 

More Than 16 Memory Areas Reserved [4] 

An attempt was made to reserve more than sixteen memory areas. Further requests are 
ignored. 

Reduce the number of memory areas reserved by the program. 

Negative Memory Reserved [4] 

An attempt was made to reserve memory. The end address was smaller that the start 
address. 

Correct the memory reservation in the source program. 

Rel Branch Out of Range [16] 

A relative branch around a PAGE or ORG directive resulted In a branch out of range 
when that directive was accounted for in the link editor. 
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Either remove the PAGE or ORG directive, or use a branch around a JMP instruction to 
get the needed range. 

Unresolved External Ref [8] 

The label listed was referenced but not found. 

If the label is in a subroutine library, insurethat all subroutine libraries areavailableand 
on the same disk. If not, the program must be corrected to either providethe label or not 
reference it. 

ZP Reference to Non-ZP Label [4] 

The listed label Is not a zero page label. A subroutine has referenced it as a zero page 
label. 

Make the label a zero page label or remove the square brackets around the reference to 
this label. Reassembly will be required to do this. 

Terminal Link Editor Errors 

These errors will cause the link editor to quit and return to the monitor. 

Catalog Full 

An attempt to save the output file was made to a disk which had no free space in the 
catalog. 

Delete some files or output to a different disk. 

Disk Full 

A sector was needed to save the output file on the disk, but there was no room left. 

Place all object files for the program on a disk by themselves. Subroutine library files 
can go on a different disk, so long as all of them are on the same disk. If a number of 
partial assemblies have been done, delete all object files and reassemble the entire 
program. 

File Format Error 

The object module has a format error. This can happen if the disk is bad, or if the PEEK 
command has been used to improperly modify the object module. 

If PEEK has not been used, reassemble on a different disk. If the error persists, report 
the problem. 
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Keep File Locked 

The output file is locked. 

Change the output file name, rename the old file, or unlock the old file. 

Root File Not Found 

The root file was not found on the disk on which it was expected. 

Check for spelling errors or files by the same name as the root file that are not type R 
files. 

Symbol Table Overflow 

The symbol table, which contains global labels, has been filled up. 

This should be a rare problem, since the symbol table can hold well over 1000 labels. 
The only solution is to reduce the number of global labels in the program. 

Too Many DATA Areas 

More than eight data areas were defined. 

Eliminate the excess data areas. If necessary, reassemble with some of them combined. 



Appendix B 

The 6502 Instruction Set 

6502 Architecture 


The 6502 is an eight bit general purpose microprocessor chip. It Is used as the CPU for 
the Apple II computer. It has six Internal registers, eleven addressing modes, and fifty- 
six instructions. 

Only three of the 6502 registers are user registers, and they are all eight bit registers. 
Only one of them, the accumulator or A register, can be used for math and logic 
operations. The other two user registers are used primarily as index registers. 

The instruction set is a bit more limited than the Z80 or any of the new sixteen and thirty- 
two bit chips. This is offset somewhat by a very comprehensive set of addressing 
modes. These addressing modes, and the lower average number of machine cycles 
needed to execute a typical Instruction, make the 6502 one of the faster eight bit 
processors available. In fact, a Z80 must be clocked about twice as fast as a 6502 to run 
the same algorithm in the same time. 

In examining the 6502 instruction set, pay close attention to the zero page addressing 
modes. Careful use of zero page memory ($0000 to $00FF) can speed up and shorten a 
program significantly. 
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The Registers 

The Accumulator 

The accumulator is the principal register under user control. It is used for math and 
logical operations and indexed load and store commands. 

Indexing Registers 

The X and Y registers are user registers primarily intended for indexing. They cannot be 
used for math or logical operations. 

Program Counter 

This is a 16 bit register which contains the address of the next byte to be processed by 
the CPU chip. It is not directly available to the user. 

Stack Pointer 

This register points to the next available location on the program stack. It is not 
generally used directly by the programmer, but can be set or read. 

Processor Status 

This register contains several flags indicating results of previous operations. The status 
of theseflagsare usually tested using relative branch instructions. Theflagsare listed In 
the following table, where0 Is the least significant bit position. The code given in the last 
column is the abbreviation for the status bit. 

Bit Flag Code 

7 Sign N 

6 Overflow V 

5 Unused 

4 Break B 

3 Decimal D 

2 Interrupt I 

1 Zero Z 

0 Carry C 

If the processor status register is displayed as a binary number, the bits would 
appear in the following order: 


NV-BDIZC 
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Addressing Modes 

Implied Addressing 

This addressing mode is used with instructions that operate on internal registers. These 
instructions do not reference an address, so the operation code is the only byte 
required. 

Immediate Addressing 

The Immediate addressing mode is used by load, compare and arithmetic instructions. 
The byte to be used follows the operation code. Instructions using this type of 
addressing require two bytes. 

Absolute Addressing 

Instructions which use absolute addressing require three bytes. The first byte is the 
operation code, followed by a sixteen bit address. The address is a pointer to a load or 
store location, or In the caseof the JMPand JSR instructions, is the address to continue 
processing from. The operation indicated by the operation code Is performed on the 
byte pointed to by the absolute address. 

Zero Page Addressing 

This Is a specialized form of absolute addressing. It requires only two bytes of memory, 
since the one byte address points to the first 256 bytes of memory. A high order leading 
byte of zero in the address is implied. 

Relative Addressing 

Relative addressing requires two bytes, a one byte operand and a one byte relative 
address. Relative addressing is used only by conditional branching instructions. If the 
condition being tested for is true, the relative address Is added to the address of the 
instruction plus two. Processing continues at the new address (i.e., a branch is taken). 

A relative branch has a limited range. The branch can go forward 129 bytesor back 126 
bytes from the beginning of the instruction. If a conditional branch must be made 
outside the range of the relative branch, the instruction must be replaced by a branch 
around the longer range JMP instruction. 

For example. In order to branch on minus to HERE, If HERE is outside of the range of a 
relative branch instruction, it would be necessary to code 

BPL PAST BRANCH ON PLUS 

JMP HERE JUMP TO HERE 

PAST . . . 
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The advantage of relative branch instructions is that they are shorter and faster than 
absolute jumps. 

Absolute Indexed Addressing 

Instructions which use this form of addressing are three bytes long. One of the index 
registers (X or Y) is used as a displacement past the absolute sixteen bit address 
contained in the last two bytes of the instruction. Functionally, the value of the register 
Is added to the absolute address, and the operation Is performed on the new location. 
Both the absolute address and the index register remain unchanged by the operation. 

Zero Page Indexed Addressing 

This is identical to absolute Indexed addressing, except that the address is now a single 
byte. The first byte of the address Is assumed to be zero. The advantage over absolute 
Indexed addressing is the shorter length (two bytes) and faster execution time of the 
Instruction. In general only the X register can be used as an index register. The Y 
register is used only for the LDX and STX instructions. 

Indirect Addressing 

The only instruction that uses true Indirect addressing on the 6502 Is the JMP 
Instruction. The two byte address points to the address of the Instruction that will be 
executed next. 

Indexed Indirect Addressing 

In this two byte form of addressing, the X register is added to the zero page address In 
the second byte of the instruction. The resulting address points to a location in zero 
page memory. The operation Is performed on the byte pointed to by the address at the 
zero page location. 

Indirect Indexed Addressing 

This form of addressing also requires two bytes. The Y register is added to the two byte 
address pointed to by the second byte of the Instruction. The operation is performed on 
the location pointed to by the resulting address. Since the instruction only uses a one 
byte address, the indirect address must be In zero page memory. 

Accumuiator 

The accumulator addressing mode Is a form of Implied addressing. The operation is 
performed on the accumulator. 
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The Stack 

The 6502 is a stack oriented microprocessor. It uses a 256 byte stack, located in page 
one of memory ($100 to $1FF). This stack is used to store return addresses from 
interrupts and subroutine calls, the processor status at the time of interrupt, and as 
temporary data storage by the programmer. 

The stack pointer is an internal register which points tothe next available location in the 
stack. When information is stored in the stack (referred to as pushing ontothe stack), it 
is placed at the location pointed to by the stack pointer. The stack pointer Is then 
decremented to point to the next available stack location. 

Recovery of information from the stack is referred to as pulling from the stack. When 
this occurs, the stack pointer Is first incremented. It now points to the last byte stored on 
the stack. The byte the the stack pointer points to Is loaded. 

All of this happens internally to the processor. Generally, the stack should bethought of 
as a first In, last out storage device. The term “stack” comes from thinking of it as a stack 
of variables. When a new one is added, it is stacked on top of the current pile of 
variables. Pulling a variable from the stack removes the top variable. 

Memory Organization 

Memory is addressed with asixteen bit number. The normal division of this address Into 
two bytes, along with some hardware features of the 6502, have resulted in breaking 
memory down into a series of 256 byte sections called pages. Each page consists of all 
of the memory locations whose addresses have the same first byte. 

The 6502 recognizes two special pages, zero page and the stack buffer. Zero page, as Its 
name Implies, extends from $0000 to $00FF. It should be used for variable storage and 
pointers, since most instructions have a special zero page addressing mode. Zero page 
addressing is faster and requires less memory than addressing to other pages. 

Page one ($0100 to $01FF) is used for the stack. It should only be used by stack 
instructions. 

Pages have one other significance. Crossing a page boundary by a branch or indexing 
instruction generally takes one more machine cycle than if a page boundary was not 
crossed. This can be important If time is of the utmost importance. See Individual 
instruction descriptions to find out which instructions are effected by this. 
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Instructions 


This section contains a detailed description of the instructions available on the 6502. 
Once the basic function of each instruction is understood, it will be more convenient to 
use the reference card. The format here is more for instruction than reference. 

The description of each instruction is followed by a table which lists all addressing 
modes valid for that instruction. The hexadecimal value of the operation code Is In 
column two. Column three gives the length of the instruction In bytes. The number of 
clock cycles required to execute the instruction Is In column four. The last column 
shows the form for coding the assembly language Instruction. (See chapter four, 
section two for details on coding formats.) Conditon flags that can be changed by an 
Instruction are listed above the table of addressing modes. 

If an instruction time is followed by an asterisk, add one clock cycletothe time given If a 
page boundary is crossed during execution. 

To compute the actual time required for execution of an instruction or series of 
Instructions, remember that the Apple II clock cycles at approximately one megahertz. 
This means that there are about one million clock cycles per second. 


Implied Operand Instructions 

The following instructions are all one byte long. Any memory accessing is from the 
stack. 

BRK - Force Break 

Program execution is halted. The program counter Is incremented by two and pushed 
onto the stack, high byte first. The break flag is set, and the processor status byte is 
pushed onto the stack. Processing continues at the address pointed to by $FFFE. 


Flags Modified: B 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

00 

1 

7 BRK 


CLC - Clear Carry Flag 

The carry bit of the program status register is set to zero. 


Flags Modified: C 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

18 

1 

2 CLC 
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CLD - Clear Decimal Flag 

The decimal flag of the processor status register is set to zero. Further math operations 
are in binary arithmetic. 


Flags Modified: D 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

D8 

1 

Z CLD 


CLI - Clear Interrupt Mask 

The interrupt flag is set to zero, allowing interrupts. 


Flags Modified: I 


Addressing 

Hex 

Byt es 

Cycles 

Form 

Implied 

68 

1 

2 

CLI 

CLV - Clear Overflow Flag 




The overflow flag Is set to zero. 





Flags Modified: V 

Addressing 

Hex 

Bytes 

Cycles 

Form 

Implied 

B8 

1 

2 

CLV 


DEX - Decrement X 

The contents of the X register are decremented by one. If the result is zero Z=1, 
otherwise Z=0. If the result Is negative (bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

CA 

1 

2 DEX 
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DEY - Decrement Y 

The contents of the Y register are decremented by one. If the result is zero Z=1, 
otherwise Z=0. If the result Is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Byt es 

Cycles Form 

Implied 

88 

1 

2 DEY 


INX - Increment X 

The contents of the X register are incremented by one. If the result Is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1. otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

E8 

1 

2 INX 


INY - Increment Y 

The contents of the Y register are incremented by one. If the result Is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

C8 

1 

2 INY 


NOP - No Operation 
Does nothing for two cycles. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

EA 

1 

2 NOP 
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PHA - Push A 

The accumulator is pushed onto the stack. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

48 

1 

3 PHA 


PHP - Push Processor Status 

The processor status register is pushed onto the stack. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

08 

1 

3 PHP 


PLA - Pull A 

The accumulator is pulled from the stack. If the result is zero Z=1, otherwise Z=0. If the 
result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

68 

1 

4 PLA 


PLP - Pull Processor Status 

The processor status register is pulled from the stack. 

Flags Modified: N V B D I Z C 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

28 

1 

4 PLP 
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RTI - Return From Interrupt 

The processor status, low byte of the program counter, and high byte of the program 
counter are pulled from the stack, in the order listed. The program counter is then 
incremented by one. This returns from a hardware interrupt. 

Flags Modified: N V B D I Z C 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

40 

1 

6 RTI 


RTS - Return From Subroutine 

The program counter is pulled from the stack, low byte first, and incremented. This has 
the effect of returning to the instruction following the last JSR instruction. 


Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Implied 

60 

1 

6 

RTS 

SEC - Set Carry 





The carry flag is 

set to one. 






FI 

ags Modified: C 

Addressing 

Hex 

Bytes 

Cycles 

Form 

Implied 

38 

1 

2 

SEC 


SED - Set Decimal Mode 

The decimal flag is set to one. Further math operations are performed in decimal 
arithmetic. 


Flags Modified: D 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

F8 

1 

2 SED 
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SEI - Set Interrupt Flag 

The interrupt flag is set to one, preventing interrupts. 

Flags Modified: I 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

78 

1 

2 SEI 


TAX - Transfer A to X 

Transfer the contents of the accumulator to the X register. If the result Is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

AA 

1 

2 TAX 


TAY - Transfer A to Y 

Transfer the contents of the accumulator to the Y register. If the result Is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

A8 

1 

2 TAY 


TSX - Transfer S to X 

Transfer the contents of the stack pointer to the X register. If the result is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

BA 

1 

2 TSX 
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TXA - Transfer X to A 

Transfer the contents of the X register to the accumulator. If the result is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

8A 

1 

3 TXA 


TXS - Transfer X to S 

Transfer the contents of the X register to the stack pointer. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

9A 

1 

2 TXS 


TYA - Transfer Y to A 

Transfer the contents of the Y register to the accumulator. If the result is zero Z=1, 
otherwise Z=0. If the result Is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles Form 

Implied 

98 

1 

2 TYA 


Branching Instructions 

With the exception of the JMP and JSR instructions, all branches on the 6502 are both 
conditional and relative. Note that two times are given for relative addressing. The first 
applies if the branch is not taken. The second is for taking the branch. As noted, an 
additional cycle is required if the branch crosses a page boundary. 
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BCC - Branch on Carry Clear 

Branch if the carry flag is zero. This instruction can also be coded as BLT, meaning 
branch on less than. BLT is not a standard 6502 mnemonic. It is included as an alias for 
BCC because it is more natural for branching after a compare instruction. (If the carry 
flag is clear after a compare Instruction, It implies that the register compared was less 
than the memory location it was compared to.) 

Flaigs Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Relative 

90 

2 

2,3* 

BCC 

BLT 


BCS - Branch on Carry Set 

Branch If the carry flag is one. This instruction can also be coded as BGE, meaning 
branch on greater than or equal. BGE Is not a standard 6502 mnemonic. It Is Included as 
an alias for BCS because It is more natural for branching after a compare instruction. (If 
the carry flag Is set after a compare Instruction, the register that was compared was 
greater than or equal to the memory location it was compared to.) 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Relative 

BO 

2 

2,3* 

BCS 

BGE 

ABS 

ABS 


BEQ - Branch if Equal 

Branch If the zero flag is one. This indicates a zero result from the last load or arithmetic 
instruction, or an equal condition from the last compare Instruction. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Relative 

FO 

2 

2,3* 

BEQ 


BGE - Branch If Greater Than or Equal 

This Is an alias for BCS, not a standard 6502 instruction. It Is used to branch after 
compare instructions. See BCS. 
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BMI - Branch if Minus 

Branch if the minus flag (N) is one. The N flag is set after load, arithmetic and compare 
Instructions. It matches bit seven of the result (most significant bit). For signed 
arithmetic, bit seven Is the sign bit, and Is one for a negative number. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles Form 

Relative 

30 

2 

2,3* BMI 


BNE - Branch if Not Equal 

Branch if the zero flag is zero. This Indicates a non-zero result form the last load, 
arithmetic, or compare instruction. 


Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Relative 

DO 

2 

2,3* 

BNE ABS 


BLT - Branch if Less Than 

This is an alias for BCC, not a standard 6502 instruction. It is used after compare 
instructions to branch if the register was less than the memory location it was compared 
to. See BCC. 

BPL - Branch if Plus 

Branch if the sign flag (N) Is zero. The sign flag Is set by load, arithmetic and compare 
instructions to the value of bit seven of the result (most significant bit). For signed 
arithmetic, bit seven is the sign bit, and is zero for positive numbers. 


Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Relative 

10 

2 

2,3* 

BPL ABS 
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BVC - Branch on Overflow Clear 

Branch if the overflow flag (V) is zero. The overflow flag is cleared by arithmetic 
instructions if the sign bit did not change during the math operation. It is also effected 
by the BIT instruction, which sets it to the value of bit six of the result (next most 
significant bit). 


Flags Modified; none 


Addressing 

Hex 

Byt es 

Cycles 

Form 

Relative 

50 

3 

3,3* 

BVC 


BVS - Branch on Overflow Set 

Branch if the overflow flag (V) is one. The overflow flag Is set by a math operation if the 
value of the sign bit was changed as a result of the operation. It is also set to the value of 
bit six after a BIT instruction. 


Flags Modified: none 


Addressing 

Hex 

Byt es 

Cycles 

Form 

Relative 

70 

3 

3,3* 

BVS ABS 


JMP - Jump 

A new address is loaded into the program counter. Execution continues from the new 
address. This is equivalent to the GOTO statement in most high level languages. 

Flags Modified: none 


Addressing 

Hex 

Byt es 

Cycles 

Form 

Absolute 

4C 

3 

3 

JMP 

Indirect 

6C 

3 

6 

JMP 
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JSR - Jump to Subroutine 

The program counter is incremented by two and pushed on the stack, high byte first. 
The address in the last two bytes of the instruction is loaded Into the program counter; 
execution continues at that address. Assuming an unmolested stack, the next RTS 
instruction will cause program execution to resume with the instruction after the JSR. 
This Is equivalent to a CALL statement In most high level languages. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 

Absolute 

20 

3 

6 

JSR 


Load and Store Instructions 

LDA -Load Accumulator 

The accumulator is loaded from the specified memory location. If the result iszeroZ=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

AD 

3 

4 

LDA 

ABS 

Zero Page 

A5 

2 

3 

LDA 

ZP 

Immediate 

A9 

2 

2 

LDA 

#ZP 

Absolute,X 

BD 

3 

4* 

LDA 

ABS,X 

Absolutely 

B9 

3 

4 * 

LDA 

ABS,Y 

(Indirect,X) 

A1 

2 

6 

LDA 

(ZP,X) 

(Indirect) , Y 

B1 

2 

6* 

LDA 

(ZP),Y 

Zero Page,X 

B5 

2 

4 

LDA 

ZP,X 
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LDX - Load X Register 

The X register is loaded from the specified memory location. If the result is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

AE 

3 

4 

LDX 

ABS 

Zero Page 

A6 

2 

3 

LDX 

ZP 

Immediate 

A2 

2 

2 

LDX 

#ZP 

Absolute,Y 

BE 

3 

4* 

LDX 

ABS,Y 

Zero Page,Y 

B6 

2 

4 

LDX 

ZP,Y 


LDY - Load Y Register 

The Y register is loaded from the specified memory location. If the result is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

AC 

3 

4 

LDY 

ABS 

Zero Page 

A4 

2 

3 

LDY 

ZP 

Immediate 

AO 

2 

2 

LDY 

#ZP 

Absolute,X 

BC 

3 

4* 

LDY 

ABS,X 

Zero Page,X 

B4 

2 

4 

LDY 

ZP,X 


STA Store Accumulator 

The contents of the accumulator are copied to the specified memory location. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

8D 

3 

4 

STA 

ABS 

Zero Page 

85 

2 

3 

STA 

ZP 

Absolute,X 

9D 

3 

5 

STA 

ABS,X 

Absolute,Y 

99 

3 

6 

STA 

ABS,Y 

(Indirect,X) 

81 

2 

6 

STA 

(ZP,X) 

(Indirect),Y 

91 

2 

6 

STA 

(ZP),Y 

Zero Page,X 

96 

2 

4 

STA 

ZP,X 
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STX - Store X Register 

The contents of the X register are copied to the specified memory location. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

8E 

3 

4 

STX 

ABS 

Zero Page 

86 

2 

3 

STX 

ZP 

Zero Page,Y 

96 

2 

4 

STX 

ZP,Y 


STY - Store Y Register 

The contents of the Y register are copied to the specified memory location. 

Flags Modified: none 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

8C 

3 

4 

STY 

ABS 

Zero Page 

84 

2 

3 

STY 

ZP 

Zero Page,X 

94 

2 

4 

STY 

ZP,X 
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Logical and Arithmetic Instructions 

ADC - Add With Carry 

The contents of the accumulator are added to the contents of the specified memory 
location. If the carry bit is set, the result is incremented by one. If the sign bit (bit seven) 
was changed by the addition, the overflow flag is set, otherwise it is cleared. If the result 
was larger than 255, the carry flag Is set. The result Is left in the accumulator. Setting of 
the carry flag on overflow allows multiple byte numbers to be conveniently added, from 
least to most significant byte. 

This instruction can operate using binary or decimal arithmetic, depending on the D 
flag. In decimal arithmetic, ninety-nine is the highest number that can be held in the 
accumulator. The carry flag is set for results over ninety-nine. 

Flags Modified: N V Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

6D 

3 

4 

ADC 

ABS 

Zero Page 

65 

2 

3 

ADC 

ZP 

Immediate 

69 

2 

2 

ADC 

#ZP 

Absolute, X 

7D 

3 

4 * 

ADC 

ABS,X 

Absolute,Y 

79 

3 

4 * 

ADC 

ABS,Y 

(Indirect,X) 

61 

2 

6 

ADC 

(ZP,X) 

(Indirect),Y 

71 

2 

6* 

ADC 

(ZP),Y 

Zero Page,X 

75 

2 

4 

ADC 

ZP,X 


AND - Logical AND 

A logical AND is performed using the accumulator and the specified memory location. 
The result is left in the accumulator. If the result Is zeroZ=1, otherwiseZ=0. If the result 
is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

2D 

3 

4 

AND 

ABS 

Zero Page 

25 

2 

3 

AND 

ZP 

Immediate 

29 

2 

2 

AND 

#ZP 

Absolute,X 

3D 

3 

4 * 

AND 

ABS,X 

Absolute, Y 

39 

3 

4 * 

AND 

ABS,Y 

(Indirect,X) 

21 

2 

6 

AND 

(ZP,X) 

(Indirect),Y 

31 

2 

5* 

AND 

(ZP),Y 

Zero Page,X 

35 

2 

4 

AND 

ZP,X 
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ASL - Arithmetic Shift Left 

Shift the contents of the specified memory location left one bit. A zero comes in on the 
right (least significant bit). Bit seven replaces the carry flag. If the result is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Accumulator 

OA 

1 

2 

ASL 

A 

Absolute 

OE 

3 

6 

ASL 

ABS 

Zero Page 

06 

3 

5 

ASL 

ZP 

Absolute, X 

IE 

3 

7 

ASL 

ABS,X 

Zero Page,X 

16 

2 

6 

ASL 

ZP,X 


BIT - Compare Memory and Accumulator 

A logical AND is performed between the accumulator and the specified memory 
location, but not stored. The zero flag is one if the result is zero, and zero otherwise. Bits 
six and seven of the result are stored in the V and N flags, respectively. 


Flags Modified: Z V N 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

2C 

3 

4 

BIT 

ABS 

Zero Page 

24 

2 

3 

BIT 

ZP 


CMP - Compare Accumulator and Memory 

The specified memory location is subtracted from the accumulator. The results are not 
stored, and the accumulator is left unchanged. If the result is zero Z=1, otherwise Z=0. If 
the result is negative (bit seven set) N=1, otherwise N=0. If the accumulator is smaller 
than the memory location then C=0, otherwise C=1. 

CMP Is normally followed by a branch. BCC branches If A < memory, BEQ branches if A 
= memory, BCS branches if A > = memory, and BNE branches if A > memory. Note that 
BCC and BCS have alias names of BLT and BGE, respectively. These names are more 
mnemonic for the purpose of branching after a compare. 
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CMP can also be coded as CPA. This corresponds more closely to the format of the CPX 
and CPY commands, below. 


Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

CD 

3 

4 

CMP 

ABS 





CPA 

ABS 

Zero Page 

C5 

2 

3 

CMP 

ZP 





CPA 

ZP 

Immediate 

C9 

2 

2 

CMP 

#ZP 





CPA 

#ZP 

Absolute,X 

DD 

3 

4* 

CMP 

ABS,X 





CPA 

ABS,X 

Absolutely 

D9 

3 

4* 

CMP 

ABS,Y 





CPA 

ABS,Y 

(Indirect,X) 

Cl 

2 

6 

CMP 

(ZP,X) 





CPA 

(ZP,X) 

(Indirect) , Y 

D1 

2 

5* 

CMP 

(ZP),Y 





CPA 

(ZP),Y 

Zero Page,X 

D5 

2 

4 

CMP 

ZP,X 





CPA 

ZP,X 


CPA - Compare Accumulator and Memory 

This is an alias for CMP, not a normal 6502 instruction. It is included to make macro 
coding easier by corresponding more closely to the format of CPX and CPY. See above 
for a description of CMP. 

CPX - Compare X Register and Memory 

The specified memory location is subtracted from the X register. The result Is not 
stored. If the result is zero Z=1, otherwise Z=0. If the result is negative (bit seven set) 
N=1, otherwise N=0. If the X register is smaller than the memory location C=0, 
otherwise C=1. See CMP for branching possibilities. 


Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

EC 

3 

4 

CPX 

ABS 

Zero Page 

E4 

2 

3 

CPX 

ZP 

Immediate 

EO 

2 

2 

CPX 

#ZP 
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CPY - Compare Y Register and Memory 

The specified memory location is subtracted from the Y register. The result Is not 
stored. If the result is zero Z=1, otherwise Z=0. If the result is negative (bit seven set) 
N=1, otherwise N=0. If the Y register Is smaller than the memory location C=0, 
otherwise C=1. See CMP for possible branches. 

Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

CC 

3 

4 

CPY 

ABS 

Zero Page 

C4 

3 

3 

CPY 

ZP 

Immediate 

CO 

2 

2 

CPY 

#ZP 


DEC - Decrement Memory 

The specified memory location is decremented by one. If the result is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

CE 

3 

6 

DEC 

ABS 

Zero Page 

C6 

2 

5 

DEC 

ZP 

Absolute,X 

DE 

3 

7 

DEC 

ABS,X 

Zero Page,X 

D6 

2 

6 

DEC 

ZP,X 


EOR - Exclusive OR With Accumulator 

The contents of the accumulator are exclusive ORed with the specified memory 
location. The result is left in the accumulator. If the result Is zero Z=1, otherwise Z=0. If 
the result is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

4D 

3 

4 

EOR 

ABS 

Zero Page 

45 

2 

3 

EOR 

ZP 

Immediate 

49 

2 

2 

EOR 

#ZP 

Absolute, X 

5D 

3 


EOR 

ABS,X 

Absolute, Y 

59 

3 

4* 

EOR 

ABS,Y 

(Indirect,X) 

41 

2 

6 

EOR 

(ZP,X) 

(Indirect),Y 

51 

2 

5* 

EOR 

(ZP),Y 

Zero Page,X 

55 

2 

4 

EOR 

ZP,X 
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INC - Increment Memory 

The contents of the specified memory location are incremented by one. The result Is 
stored back in the memory location. If the result is zero Z=1, otherwise Z=0. If the result 
Is negative (bit seven set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

EE 

3 

6 

INC 

ABS 

Zero Page 

E6 

3 

6 

INC 

ZP 

Absolute,X 

FE 

3 

7 

INC 

ABS,X 

Zero Page,X 

F6 

2 

6 

INC 

ZP,X 


LSR - Logical Shift Right 

Shift the specified memory location right by one bit. A zero is rotated into the most 
significant (left) bit position. The least significant bit Is dropped off Into the carry flag. If 
the result is zero Z=1, otherwise Z=0. If the result Is negative (bit seven set) N=1, 
otherwise N=0. 


Flags Modified: Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Accumulator 

4A 

1 

2 

LSR 

A 

Absolute 

4E 

3 

6 

LSR 

ABS 

Zero Page 

46 

2 

6 

LSR 

ZP 

Absolute, X 

6E 

3 

7 

LSR 

ABS,X 

Zero Page,X 

66 

2 

6 

LSR 

ZP,X 
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ORA - Inclusive OR With Accumulator 

The accumulator is ORed with the specified memory location. The result Is left in the 
accumulator. If the result is zero Z=1, otherwise Z=0. If the result Is negative (bit seven 
set) N=1, otherwise N=0. 

Flags Modified: N Z 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

OD 

3 

4 

ORA 

ABS 

Zero Page 

05 

2 

3 

ORA 

ZP 

Immediate 

09 

2 

2 

ORA 

#ZP 

Absolute, X 

ID 

3 

4 * 

ORA 

ABS,X 

Absolute,Y 

19 

3 

4 * 

ORA 

ABS,Y 

(Indirect,X) 

01 

2 

6 

ORA 

(ZP,X) 

(Indirect),Y 

11 

2 

5* 

ORA 

(ZP),Y 

Zero Page,X 

16 

2 

4 

ORA 

ZP,X 


ROL - Roll Left 

The specified memory location is shifted left by one bit. The carry flag Is replaced by bit 
seven (most significant bit). The old carry flag is rolled Into the right most (least 
significant) bit position. If the result is zero Z=1, otherwise Z=0. If the result is negative 
(bit seven set) N=1, otherwise N=0. 


Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Accumulator 

2A 

1 

2 

ROL 

A 

Absolute 

2E 

3 

6 

ROL 

ABS 

Zero Page 

26 

2 

6 

ROL 

ZP 

Absolute, X 

3E 

3 

7 

ROL 

ABS,X 

Zero Page,X 

36 

2 

6 

ROL 

ZP,X 
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ROR - Roll Right 

The specified memory location is shifted right by one bit. The carry flag is placed In the 
left (most significant) bit position. The least significant (right most) bit drops off Into the 
carry flag. If the result is zero Z=1, otherwise Z=0. If the result Is negative (bit seven set) 
N=1, otherwise N=0. 


Flags Modified: N Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Accumulator 

6A 

1 

2 

ROR 

A 

Absolute 

6E 

3 

6 

ROR 

ABS 

Zero Page 

66 

2 

5 

ROR 

ZP 

Absolute, X 

7E 

3 

7 

ROR 

ABS,X 

Zero Page,X 

76 

2 

6 

ROR 

ZP,X 


SBC - Subtract With Carry 

Subtract the specified memory location from the accumulator, storing the result in the 
accumulator. Decrement the result if the carry flag Is clear. If a borrow from the next 
most significant byte was made, the carry flag is cleared; If not. It Is set. If the sign bit (bit 
seven) was changed by the operation V=1, otherwise V=0. If the result Is zero Z=1, 
otherwise Z=0. If the result is negative (bit seven set) N=1, otherwise N=0. 

Subtracts normally begin by setting the carry flag. Subtraction of multiple byte 
numbers can then be made, proceeding from the least significant to most significant 
bytes. The carry flag keeps track of borrowing. 

The SBC instruction can function as a binary or decimal subtract, depending on the 
decimal flag of the processor status register. 

Flags Modified: N V Z C 


Addressing 

Hex 

Bytes 

Cycles 

Form 


Absolute 

ED 

3 

4 

SBC 

ABS 

Zero Page 

E5 

2 

3 

SBC 

ZP 

Immediate 

E9 

2 

2 

SBC 

#ZP 

Absolute^ X 

FD 

3 

4 * 

SBC 

ABS,X 

Absolutely 

F9 

3 

4 * 

SBC 

ABS,Y 

(Indirect, X) 

El 

2 

6 

SBC 

(ZP,X) 

(Indirect) ,Y 

FI 

2 

5* 

SBC 

(ZP),Y 

Zero Page,X 

F5 

2 

4 

SBC 

ZP,X 












Appendix C 
Instruction Summaries 


Monitor Instructions 

This section contains a listing of the monitor commands by priority. This is not quite 
alphabetical order; LOAD Is out of alphabetical order. The order listed allows the 
number of letters needed to specify a given command to be determined, as explained in 
chapter two, where a complete descriptions of the commands is also found. 


APPEND XXX 

append file xxx 

ASML 

assemble and link 

ASMLG 

assemble, link and go 

ASSEMBLE 

assemble the file in memory 

BRUN XXX 

execute file xxx 

CATALOG XXX 

catalog the disk 

CMPL 

compile and link 

CMPLG 

compile, link and go 

CHECK 

check a disk 

COMPILE 

compile the file in memory 

COMPRESS 

compress the disk 

COPY 

copy files 

DELETE XXX 

delete file xxx from disk 

DOS 

boot DOS from slot x 

EDIT 

soft entry to text editor 

EXPAND 

expand load 

FREE 

display memory used 

LOAD XXX 

load file xxx 

LINK 

link edit 

LOCK XXX 

lock file xxx 

MARGIN X 

set the left margin to x 

NEW 

hard entry to text editor 

NOEXPAND 

don’t expand load 
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PEEK 

examine and change disk sectors 

PRINT 

print file 

PROFF 

turn printer off 

PRON 

turn printer on 

QUIT 

exit the assembler 

RENAME XXX, yyy 

rename file xxx 

RESET 

reset modification count 

RESTORE XXX 

restore file xxx 

RUN 

assemble, link and execute a program 

SAVE XXX 

save file xxx 

SWITCH XXX, yyy 

switch files 

TAB 

set tab line 

TIME 

print the time and date 

UNLOCK XXX 

unlock file xxx 

USER 

call the SUSER subroutine In the 
operating system 

VOLUME X 

set the volume number to x 

Text Edit Commands 

Text edit commands are divided into two categories: escape commands and control key 
commands. Escape commands are entered from the escape mode. The escape mode is 
entered via the escape key and remains active until a non escape mode key Is pressed. 
Control key commands are entered by holding the CTRL key down whilethe command 

key is pressed. 


Control Commands 


CTRL A 

tab right 

CTRL B 

home to bottom of page 

CTRL C 

search and replace up 

CTRL D 

clear to end of line 

CTRL E 

home to end of line 

CTRL F 

home to top of file 

CTRL G 

shift display window 

CTRL 1 

toggle display 

CTRL K 

left bracket 

CTRL L 

home to end of file 

CTRL N 

switch return mode 

CTRL O 

shift lock 

CTRL P 

pop lines from buffer 

CTRL Q 

quit 

CTRL R 

remove blank lines 

CTRL S 

tab left 

CTRL T 

home to top of page 

CTRL V 

search and replace down 

CTRL W 

home to start of line 
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CTRL X string search down 

CTRL Y switch cursor mode 

CTRL Z string search up 

Escape Commands 


[ESC] B 

insert a line 

[ESC] C 

scroll screen down 

[ESC] E 

scroll screen up 

[ESC] F 

display memory used 

[ESC] G 

delete a character 

[ESC] H 

insert a character 

[ESC] I 

move cursor up 

[ESC] J 

move cursor left 

[ESC] K 

move cursor right 

[ESC] M 

move cursor down 

[ESC] O 

delete lines to buffer 

[ESC] P 

copy lines to buffer 

[ESC] W 

scroll screen up one page 

[ESC] X 

scroll screen down one page 

[ESC] Y 

delete a line 

[ESC] * 

enter search string 

[ESC] : 

enter replace string 

[ESC] -> 

insert a character from the buffer 

[ESC] <- 

delete a character to the buffer 

[ESC] ! 

vertical bar 

[ESC] ( 

left curly bracket 

[ESC] ) 

right curly bracket 

[ESC] ( 

left square bracket 

[ESC] ) 

right square bracket 

[ESC] % 

at sign 

[ESC] " 

up arrow 

[ESC] / 

Backslash 

[ESC] _ 

Underline 

[ESC] 4- 

Tilde 


Assembler Directives 

The following table lists all of the assembler directives valid in this assembler. Most of 
these assembler directives require an operand field, but the form varies so much that 
these fields are not described here. Refer to chapter four to check the valid operands for 
a given directive. 

ACTR set assembler loop counter 

AIF conditional assembler branch 

AINPT assembler Input 
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AGO unconditional assembler branch 

AMID mid string function for symbolic parameters 

ANOP assembler no operation 

APEND append a source file 

ASRCH string search for symbolic parameters 

COPY copy a source file 

DATA start data area 

DC declare constant 

DS declare storage 

EJECT skip to new printer page 

END end program segment 

EQU define symbolic constant 

ENTRY define entry point 

ERROR print errors 

EXPND expand DC statements 

FPLEN set floating point length 

GBLA define global arithmetic symbolic parameter 

GBLB define global boolean symbolic parameter 

GBLC define global character symbolic parameter 

GEN generate macro expansions 

GEQU define global symbolic constant 

KEEP keep object module 

LCLA define local arithmetic symbolic parameter 

LCLB define local boolean symbolic parameter 

LCLC define local character symbolic parameter 

LIST list output 

MCOPY copy macro file 

MDROP drop macro file 

MEM reserve memory range 

MERR maximum error level 

MLOAD load macro file 

MNOTE macro note (error statement) 

MSB set most significant bit 

ORG set origin 

PAGE skip to page boundary 

PRNT sent output to the printer 

SETA set arithmetic symbolic parameter 

SETB set boolean symbolic parameter 

SETC set character symbolic parameter 

START start subroutine 

SYMBL print symbol tables 

TITLE set page headers 

USING using data area 

The following directives are only valid inside of a macro file. 
MACRO start macro 

MEND end macro 

MEXIT exit macro 
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ADC 
AND 
ASL 
BCC 
BCS 
BEQ 
BGE 
BIT 
BMI 
BNE 
BLT 
BPL 
BRK 
BVC 
BVS 
CLC 
CLD 
CLI 
CLV 
CMP 
CPA 
CPX 
CPY 
DEC 
DEX 
DEY 
EOR 
INC 
I NX 
I NY 
JMP 
JSR 
LDA 
LDX 
LDY 
LSR 
NOP 
ORA 
PHA 
PHP 
PLA 
PLP 
ROL 




' Of 9f ^ 












^ ^ ^ 
^ ^ \ \ \ ^ 


4 ? 4^ 

/ / 

/ / 

/ 


2 


2 4 4* 4* 3 4 

2 4 4* 4* 3 4 

6 7 5 6 


4 3 


7 


2 

2 

2 

2 


2 

2 


2 

2 



3 

3 

4 
4 


2 4 4* 4* 3 

2 4 4* 4* 3 

2 4 3 

2 4 3 

6 7 5 


2 4 4* 4* 3 

6 7 6 


3 

6 

2 4 4* 4* 3 

2 4 4* 3 

2 4 4* 3 

6 7 6 

2 4 4* 4* 3 


4 

4 


6 


4 

6 


4 

4 

6 

4 


6 5* 

6 5* 

3' 

3' 

3' 

3' 

3' 

3' 

3' 

3' 

3' 

3' 


6 5* 
6 5* 


6 6 * 


6 


4 


6 5* 


6 5 * 


6 


7 


5 


6 
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ROR 

RTI 

RTS 

SBC 

SEC 

SED 

SEI 

STA 

STX 

STY 

TAX 

TAY 

TSX 

TXA 

TXS 

TYA 



6 

6 

2 

2 

2 


2 

2 

2 

2 

2 

2 


6 7 5 6 


2 4 4* 4* 3 4 


4 5 5 3 4 

4 3 

4 3 4 


4 


6 5* 


6 6 


’ If branch is not taken, 2 cycles. If branch crosses page boundary, 4 cycles 
* Add 1 cycle if instruction crosses page boundary. 




INSTRUCTION SUMMARIES 


203 


Macro Library 

The macros contained in the macro libraries are listed below by category. See chapter 
six for a description of the use and definition of the operand fields. 


Floating Point (library and ROM) 


ABS 

ADI 

absolute value 

ATAN 

AD1,AD2 

arc tangent 

CHRGET 


character input initialization 

CHS 

ADI 

change sign 

cos 

AD1,AD2 

cosine 

EXP 

AD1,AD2 

exponent 

FADD 

AD1,AD3,AD3 

add 

FDIVD 

AD1,AD2,AD3 

divide 

FERR 

ADR 

set floating point error 
(SUBS only) 

FIX 

AD1,AD2 

convert to integer 

FIX4 

AD1,AD2 

convert to 4 byte integer (SUBS only) 

FLOAT 

AD1,AD2 

convert to floating point 

FL0AT4 

AD1,AD2 

convert 4 byte integer to 
floating point (SUBS only) 

FMULT 

AD1,AD2,AD3 

multiply 

FPIN 

ADR,STRING 

input 

FPOUT 

ADI 

output 

FSUB 

AD1,AD2,AD3 

subtract 

I NT 

AD1,AD2 

integer function 

LN 

AD1,AD2 

natural logarithm 

PWR 

AD1,AD2,AD3 

raise a number to a power 

RND 

ADI 

random number 

SIGN 

AD1,AD2 

sign function 

SIN 

AD1,AD2 

sine 

SQR 

AD1,AD2 

square root 

TAN 

AD1,AD3 

tangent 

Dubie Precision Floating Point 


CNVDF 

DP,FP 

convert double precision to 
single precision 

CNVFD 

FP,DP 

convert single precision to 
double precision 

DABS 

ADI 

absolute value 

DADD 

AD1,AD2,AD3 

add 

DATAN 

AD1,AD2 

tangent 

DCHS 

ADI 

change sign 

DCOS 

AD1,AD2 

cosine 
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DDIVD AD1,AD2,AD3 

DEXP AD1,AD2 

DFIX AD1,AD2 

DFIX4 AD1,AD2 

DFLOAT AD1,AD2 

DFL0AT4 AD1,AD2 

DINT AD1,AD2 

DLN AD1,AD2 

DMULT AD1,AD2,AD3 

DPIN ADR,STRING 

DPOUT ADI 

DPWR AD1,AD2,AD3 

DRND 

DSIGN AD1,AD2 

DSIN AD1,AD2 

DSQR AD1,AD2 

DSUB AD1,AD2,AD3 

DTAN AD1,AD2 

Integer Mathematics 

ADD AD1,AD2,AD3 

ADD4 AD1,AD2,AD3 

CNV24 12,14 

CNV42 14,12 

DIVD AD1,AD2,AD3 

DIV4 AD1,AD2,AD3 

lABS ADI 

IIN ADI,STRING 

lOUT ADI 

ISIGN ADI 

ISQR AD1,AD2 

I4ABS ADI 

I4IN ADI,STRING 

I40UT ADI 

I4SIGN AD1,AD2 

I4SQR AD1,AD2 

MOD AD1,AD2,AD3 

M0D4 AD1,AD2,AD3 

MULT AD1,AD2,AD3 

MUL4 AD1,AD2,AD3 

SUB AD1,AD2,AD3 

SUB4 AD1,AD2,AD3 

Logic and Branching 

ASL2 ADR 


divide 

exponent 

convert to integer 

convert to 4 byte integer 

convert from integer 

convert from 4 byte integer 

integer function 

natural logarithm 

multiply 

input 

output 

raise a number to a power 

random number 

sign function 

sine function 

square root 

subtract 

tangent 


two byte integer add 
four byte integer add 
convert two byte to four byte 
convert four byte to two byte 
two byte integer divide 
four byte integer divide 
two byte integer absolute value 
two byte Integer input 
two byte integer output 
two byte integer sign function 
two byte integer square root 
four byte Integer absolute value 
four byte integer Input 
four byte integer output 
four byte integer sign function 
four byte integer square root 
two byte modulo function 
four byte modulo function 
two byte Integer multiply 
four byte integer multiply 
two byte Integer subtract 
four byte integer subtract 


two byte arithmetic shift left 
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BGT 

BP 

branch if greater than 

BLE 

BP 

branch if less than or equal 

CMP2 

AD1,AD2,R 

two byte unsigned compare 

DBNE 

R,BP 

decrement and branch not equal 

DBNE2 

ADR,BP,R 

two byte decrement 
and branch not equal 

DBPL 

R,BP 

decrement and branch If plus 

DEC2 

AD1,R 

two byte decrement 

INC2 

ADR 

two byte increment 

JCC 

BP 

jump If carry clear 

JCS 

BP 

jump if carry set 

JEQ 

BP 

jump if equal 

JGE 

BP 

jump if greater than or equal 

JGT 

BP 

jump if greater than 

JLE 

BP 

jump if less than or equal 

JLT 

BP 

jump if less than 

JMI 

BP 

jump if minus 

JNE 

BP 

jump if not equal 

JPL 

BP 

jump If plus 

LSR2 

ADR 

two byte logical shift right 

MASL 

ADR,NUM 

multiple arithmetic shift left 

MLSR 

ADR,NUM 

multiple logical shift right 

put and Output 


GOUT 

R,G 

write character 

GROUT 

G 

Issue return 

FLASH 


set flashing characters 

GETLN 

WRD 

get a line 

HOME 


clear screen and home 

cursor 

HTAB 

NUM 

horizontal tab 

INPUT 

GHRS 

input with prompt 

INVERSE 


set inverse characters 

NORMAL 


set normal characters 

PRAX 


print A,X as hex number 

PRBL 

NUM 

print blanks 

PRBYTE 

ADR 

print accumulator In hex 

PRERR 


print ’ERR’ 

PRHEX 

ADR 

print a hex digit 

PRINT 

GHRS 

print characters with return 

PRINTG 

GHRS 

print centered characters 

PRINT2 

GHRS 

print characters without 
return 

PRNUM 


print number string 

PROMPT 

GHAR 

set prompt character 




RDKEY 

CRS 

read a character 

VTAB 

NUM 

vertical tab 

WNDB 

NUM 

set window bottom 

WNDL 

NUM 

set window left 

WNDT 

NUM 

set window top 

WNDW 

NUM 

set window width 

WRITE 

CHRS,NUM 

write characters with returi 

WRITEC 

CHRS,NUM 

write centered characters 

WRITE2 

CHRS,NUM 

write characters without 
return 

Low Resolution Graphics 


CLRGR 

ALL 

clear screen 

COLOR 


C set color 

GR 


ALL set display to low res 
graphics 

GREAD 

X,Y 

read graphics screen 

HLINE 

X1,X2,Y 

draw horizontal line 

PLOT 

X,Y 

plot a point 

VLINE 

X, Y1,Y2 

draw vertical line 

High Resolution Graphics 


HCLEAR 


clear graphics page 

HCOLOR 


C set color 

HDRAW 

X,Y 

draw a Ine 

HGR 

ALL 

display high res graphics 

HPAGE 

PAGE 

set the page to draw on 

HPLOT 

X,Y 

plot high res point 

HPOSN 

X,Y 

position the cursor 

Miscellaneous Macros 


BELL 


sound apple bell 

BUTON 

BTN,VAL 

read a button 

DW 

ADR 

define a word 

LA 

AD1,AD2,R 

load address 

LM 

AD1,AD2,R 

load memory 

MOVE 

ADI,AD2,L,R 

move memory 

PAGEl 


set display to page 1 

PAGE2 


set display to page 2 

PREAD 


PDL.VAL read a paddle 

RESTORE 


restore registers 

SAVE 


save registers 

TEXT 


display text 

WAIT 

CNT 

pause for a while 





Appendix D 
File Formats 


Text File Formats 

Overview 

All files created by the monitor, whether assembler language files or macro files, have 
exactly the same format. They are stored on disk the same way as binary files, except 
that the file type Is then changed to S. This Is done by setting bit three (saving hex $08) in 
the file type byte of the catalog entry. 

The Header 

Both source and binary files begin with four bytes of header information. The first two 
are the load address, stored least significant byte first. The next two are the length of the 
file, again stored least significant byte first. For source files, the file Itself begins with a 
second four byte header. Byte one is the language Identification byte, and Is set to one 
for assembler files. Byte two is the update number. It begins as one and is Incremented 
each time the file Is saved. 

Bytes three and four contain the date the file was last saved. The first five bits are the day 
in binary. It can range from zero to thirty-one. The next four bits contain the month 
number minus one, ranging from zero to eleven. Exceeding this range will cause the 
date printing routine of the monitor to print garbage. The last seven bits are the year 
minus 1980. The valid range isOto 127, yielding a range of years from 1980 to 2107. Note 
that the date Input routine in the operating system assumes the twentieth century when 
it allows the year to be input as two digits. 
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Text Storage 


The remainder of the source file contains lines of text in ascending order. Each line 
begins and ends with the number of bytes in the line. Adding this numberto theaddress 
of the beginning of the line gives the address of the next line. Going back one line is 
almost as easy: the value of the byte before the current line address is subtracted from 
the line address to obtain the address of the line before. The file ends with a zero. 

A simple code compression technique is used on the line before it is stored. First, all 
blanks are removed from the end of the line. All embedded blanks are replaced with the 
number of blanks in binary; thus four blanks In the middle of the line are replaced by a 
single byte containing $04.The length ofthe line isthen placed on either side of the line, 
and the line is saved. 

Two examples should help clarify this. First consider the line 

LDA ADR 

The screen characters for LDA yield the hex string 

CC C4 Cl 


while ADR is 


Cl C4 D2 


The line would appear as 

OA 07 CC C4 Cl 03 Cl C4 D3 OA 
Finally, a blank line Is stored as 


02 02 


Object Module File Formats 

Overview 

Object modules are stored by the assembler in a special file format. These files are then 
used by the link editor to produce executable programs. 

The basic unit in an object module is the subroutine, or more precisely, the program 
segment. The term program segment is used here since the file unit is not always 




FILE FORMATS 


209 


generated by a subroutine; data areas defined by the assembler also use the same 
format. The Important point is that a program segment Is a single relocatable unit, in a 
format that allows the link editor to move its position In memory, or to combine it with 
other program segments to produce a final program. 

Object modules are of type R. This file type is seen when the CATALOG command Is 
used from the monitor or from DOS. A track and sector list is used to reserve sectors for 
the file In a manner identical to that used by DOS. The file itself consists of a series of 
program segments, each of which begins on a fresh sector boundary. The program 
segment itself has two distinct parts. The first is the relocation dictionary, which 
contains the Information needed to relocate the assembled code into an arbitrary 
memory location. The second section consists of the code itself. 

The Relocation Dictionary 

The relocation dictionary is divided into fields. Some of these fields are repeatable, that 
is, they may appear any number oftimes. Aspecial field value indicates that the field has 
ended. Repeatable fields are Indicated with brackets around the parts of the field that 
can be repeated. Label lengths are input to the link editor as constants; this constant is 
referred to by the value n. The maximum label length that the link editor can handle is 
ten characters. Internally, each subroutine is assumed to have been assembled with a 
starting value of $1000. 

Bytes Definition 

1 number of sectors in program segment 

1 type 

0 -> subroutine 
1 -> data area 

1 length of labels (n) 

n program segment name 

2 displacement to relocation dictionary 

2 length of code 

2 length of reserved space to be placed at 

the end of the subroutine 

[2] location in the segment of page directive; $0000 

indicates no more directives 
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[2 location in the segment of ORG directive; $0000 
indicates no more directives 

2] value of ORG directive 

[1 label definition byte: 

$00 no more definitions 
$06 relative value past $1000 
$07 absolute value 
n label name 

1 label length attribute 

1 label type attribute 

2] label value 

[n/1 label name, 0 if no more exist 

[1 label use definition byte. If the high bit 

is set, the label value Is subtracted from 
the displacement Instead of added 
$00 no more uses 
$03 weak reference 
$04 zero page reference 
$05 select 2 byte value 
$06 select low byte 
$07 select high byte 
$08 type attribute 
$09 length attribute 
$0A count attribute 
$0B hard reference 

2 displacement in code block 

2]] offset value 

[1 relative update definition byte 

$00 no more relative references 

$02 relative branch 

$05 2 byte 

$06 low byte 

$07 high byte 

2 displacement in code block 

2] offset value 

[n/1] active data area names, $00 in first byte 
when list is exhausted 

[2 beginning of reserved area space; $0000 

indicates no more reserved space 


ORCA/M 
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2] end of reserved space 

8 $00 future expansion 

The Code Block 

The code block begins immediately after the relocation dictionary. It contains a series 
of bytes which, If outside references were resolved, would constitute the correct code at 
location $1000. The link editor uses the relocation dictionary to modify the code block 
for the actual starting location. 





Appendix E 

Adding Compilers 


This system was written to make the addition of compilers possible, both In anticipation 
of vendor-supplied compilers as well as user-written ones. The resulting compiler will 
look like it was always intended to be there if the conventions described below are 
observed. This appendix describes all of the interface requirements that a compiler 
must satisfy In order to fit into the system smoothly. 

The first thing that must be done is to inform the system that a new language exists or at 
least, that one will exist someday. This means making a few simple changes to the data 
area of the operating system. Begin by changing MAXLNG (max languages) from one 
to two, indicating that there are now two languages available. Next, change AVLANG 
(available languages) from a single byte set to one, to two bytes, each set to one. This 
indicates that both languages are currently available. Finally, add the name of the 
language right after LNAMES (language names). This should be a ten byte character 
string with no embedded blanks or commas. If the language name Is shorter than ten 
characters. It must be filled out to ten characters by adding blanks to the end of the 
name. The language name Is followed by a one byte flag, which Is one for structured 
languages (e.g. Pascal), and zero for non-structured languages (assembler). This 
indicates the default RETURN mode that the editor will use (see page 31). Reassemble 
the operating system and place the new version on the disk that will contain the 
compiler. 

The Inclusion of a language name in the operating system data area serves two 
purposes. First, it allows user selection of the current language. When the system Is 
booted, the language indicated by CLANG (current language) Is selected. If source file 
is saved via the SAVE command from the monitor, the current language number is 
saved as the first byte of the file. Each time an assembler or compiler loads a file, it 
checks to make sure that the first byte corresponds to the currently active language. If It 
Is not, It returns control to the operating system. Also, when a file is loaded from disk, 
the language name printed Is the one corresponding tothe selected languagethe list of 
names (LNAMES). When the name of a second language listed in LNAMES is typed as a 
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monitor command, the current language number is switched to its corresponding 
number. From that point on, all of the files saved have a this number as the first byte, 
until the current language Is changed. 

This means that a compiler must check the language number when it loads a file. If the 
file’s language number does not correspond to that assigned to the compiler. It should 
return to the operating system with an $FF In the X register. 

The name placed in the LNAMES field must also be the name of the compiler on the 
disk. If the operating system needs language two, for example. It loads thefile from disk 
based on the name In the second position of LNAMES. 

The last thing that must be known about a language name Is how to change It. The 
fourth byte of a compiler should be the language number, and the first three bytes 
should be JMP around this number. This allows the end user to change the language 
number to fit his own needs. By reversing the order of the LNAMES entries, changing 
the fourth byte of the assembler from two to one, and changing the fourth byte of a 
compiler from two to one, the compiler becomes the first language. (Which becomes 
active after booting). Of course, the language numbers at the beginning of each source 
file must also be changed, by loading and re-saving them. 

At this point, the system recognizes the existence of a compiler, and can create source 
files for the new language. The only thing that remains Is to explain the input, output, 
and memory usage conventions. 

When the user types ASSEMBLE from the monitor, a number of options may be added. 
Additionally, a compiler may not be the first, or last, language to be used on a given 
assembly. The information needed to initialize the compiler is contained In memory 
pages two and three. The table below shows the inputs (and outputs) from page three. 
All flags are boolean variables with 0 = FALSE and 1 = TRUE. Page two contains the list 
of subroutines to be assembled on a partial assembly. If the entire program is to be 
assembled, $200 contains a $00. This list consists of the names entered from the 
keyboard, separated by an $8D (RETURN) character. The end of the list is signaled by a 
$00. The order of the names Is the same as the order entered from the keyboard. The 
characters are Apple screen characters; that is, ASCII with the high-order bit set to one. 

Page Three Inputs/Outputs 


$300 - 

$31D 

keep file name 

$31E 


keep file volume 

$31F 


keep flag 

$321 - 

$320 

number of errors found 

$323 


list output flag 

$324 


print symbol table flag 

$325 


list errors flag 

$328 


keep file suffix letter 
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As mentioned before, a compiler may not be the first or last language used. On entry, 
the compiler should produce a .ROOT file and a .A file, and setthesuffix letterto B.The 
meanings of the .ROOT file and .A file are explained in chapter five. If the suffix letter is 
already B (or higher), then the compiler should place all subroutines in a file whose 
name is the root file name, with .B added to the end. Upon exiting the compiler, this file 
must be completed and closed, and the keep file suffix letter must be incremented. 


Besides maintaining the integrity of page two and three, a compiler must provide a 
return code in register X. The operating system will check the X register, and act 
accordingly. The return codes are listed in the table below: 

Language Return Codes 

$FF - new language needed 
$00 - processing completed 
$01 - terminal error 

If the compiler returns with a terminal error, the system will automatically enter the text 
editor with the current line at the top of the screen. The compiler must load the current 
line number in the page zero variable TP, (text pointer), at $F9.FA. 

Several areas of memory are reserved for special purposes. If a compiler needs them, it 
may use them. If it does not, it should leave them alone. 

Reserved Memory Locations 


$17 


printer on flag 

$18 


number of lines printed on current page 

$19 


current volume 

$1A 


current slot 

$1B 


current drive 

$ic 


max error allowed 

$1D 


max error found 

$1E 

$1F 

current date 

$300 - 

$34F 

language Interface 

$3F0 - 

$3FF 

reset vectors, etc. 

$6E00 - 

$6FFF 

disk sector 

$7000 - 

$8FFF 

buffer 

$B000 - 

$BFFF 

operating system 

$F800 - 

$FFFF 

monitor ROM 


Finally, all of the of the subroutines in the operating system should be examined. They 
are there to provide continuity between programs. If any of the functions that these 
subroutines do need to be performed, the operating system routines should be used. 










Appendix F 
Utility Programs 


File Conversion 


This program allows source files created by the text editor to be converted into standard 
DOS text files, and vice versa. It will only run under the ORCA/M operating system. To 
execute it, type 


BRUN CONVERT 


from the monitor. 

The program starts by presenting a menu. The operation of the program is explained 
below by describing each menu item. To perform a menu function, simply type the 
number that appears to the left of the menu item. It is not neccessary to follow this with 
the RETURN key. 

Catalog 

When a one Is typed from the main menu, a slot number Is asked for. Enter a single digit 
from four to seven, followed by the RETURN key. This is the slot of the disk that is to be 
cataloged. Next, a drive number is asked for; this must be one or two. The specified disk 
is then cataloged. The first two lines give the volume number and tells how full the disk 
is. The remainder of the page Is filled with file names in their standard format. 

If all of the file names will not fit on the screen, the line after the last file name listed has a 
flashing cursor on it. Hit any key to continue listing files. When all files have been listed, 
the bottom line will contain the message 


Hit axiy key to return to menu. 
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Convert Source to Text 

Typing a two from the main menu converts source files created by this system into 
standard DOS text files. It prompts for the name of the file to be converted. This file 
name may contain the = wildcard character discussed in chapter two. Next, the 
program asks for the source slot and source drive. This Is the disk that contains the 
source files created by the text editor. The slot and drive are entered exactly the same as 
for the catalog function. After this has been entered, it asks for the destination slot and 
drive. This is the disk where the converted text files is to be placed. (This can be the 
same disk.) The option of converting lower-case letters to upper-case Is then presented. 
Answer Y or N, for yes or no. Finally, the selections made must be confirmed. In case an 
error was made. Keying Y at this point returns to the main menu; N begins the 
conversion process. 

If the wildcard character was used In the file name, the 

Do you want prompting? 

message Is displayed. A reply of N causes all source files that fit the file name mask to be 
converted. Replying Y lets the files to be convert be selected Individually. File names for 
converted files will start with TEXT., followed by the old file name. 


Convert Text to Source 

This function works the same way as converting source files to text files, but it performs 
the opposite task. Keep in mind that the source slot and drive now point to the disk that 
has the text files on it, and the destination slot and drive point to the disk that will contain 
the source files. The created files will begin with SOURCE., followed by the original file 
name. 

Exit 

Typing a four from the main menu exits the program and returns control tothe monitor. 


Fix Sector Count 


DOS provides room for a two byte sector count, so that programs using more than 255 
sectors may be properly handled. For some reason, the CATALOG command doesn’t 
take advantage of the extra byte. This Is why sector counts under DOS never exceed 
255. The ORCA/M Operating System uses this second byte of the sector count. This 
program is provided to update the sector counts on any disks which were created using 
programs that did not use the extra byte. 
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To use the program, begin by typing 

BRUN FIX COUNT 

from the ORCA/M Monitor. The program is located on the SUBLIB.SOURCE Disk. The 
only inputs are the slot and drive number of the disk to be checked. The defaults of slot 
six, drive one may be accepted simply by typing RETURN twice. To select a different 
slot or drive, enter the appropriate slot or drive number when It is requested, and follow 
the number by the RETURN key. The program will then computethe number of sectors 
used by each file on the disk, changing any that are faulty. 

After the program has finished with the disk, it will ask If another one is to be checked. A 
default answer of Y Is provided. Any answer which starts with a Y (or simply hitting 
RETURN ) restarts the process. An answer starting with N returns control to the 
monitor. 




Appendix G 

Modifying the 
ORCA/M O/S 

The Operating System 

The ORCA/M system is designed to provide the user with the capability of tailoring the 
assembler to a particular machine configuration. To allow this, the operating system 
contains all printer interfaces, the date input routine and all subroutines required to 
interface with an eighty-column board. This allows the user to configurethe system for 
any printer, clock/calendar card or eighty-column board. 

Many of these options may be changed simply by reassembling the operating system 
with different answers to the input questions. Those that cannot be changed this way 
are detailed below. 


Printer Drivers 

The assembler has been tested with a number of different printers and interface cards. It 
should work with any interface card that works with BASIC. 

If for some reason it is neccesary to make changes, examine the routines listed below. 
Note that some purely aesthetic changes can be made, like whether a subroutine starts 
on a new page. 

SPAGE - New Page 

If the printer is currently in use, this subroutine skips to the top of the next page. It does 
not skip to a new page if it started at the top of a fresh page. 
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SPROF - Turn Off Printer 

This routine must disconnect the printer from the output hooks and send all output back 
to the standard output device (usually the monitor). 

SPRON - Initialize Printer 

The printer Is connected via the output hooks. All further output sent to the COUT 
routine in the monitor Is also sent to the printer. 

SRETN - Issues Line Feed 

This routine is based on sixty-six lines per page. As the assembler issues each linefeed, 
this routine checks to see if it Is at the bottom of a page. If so, it spaces to the next page. 

Date Input Routine 

The date Input routine Is contained entirely in the subroutine SDATE. A routine may be 
written automatically set this date if a clock card is installed. The format for the date is 
explained in appendix D. It should be placed in the two byte location DATE, at $1E. 
Another option is to replace SDATE with a subroutine that sets both bytes of DATE to 
zero. When files are loaded, the monitor will skip the portion that writes the file date out 
to the display. Files created with a date will still display the date until they are re-saved 
from the modified system. 


Eighty-Column Boards 

Users with the Videx Videoterm eighty-column board can activate It by reassembling 
the operating system. Conditional assembly branches embedded in the code will 
automatically select the code to interface with the eighty-column board. 

To work with this program, other eighty-column boards must have the capability of 
writing a single character to a specified position without scrolling the screen. Dump the 
operating system to the printer using the monitor PRINT command; this gives a 
complete listing. Including the conditional assembly branches. Next, examine the 
subroutines listed below for possible modification. 

COMMON - Common Data Area 

COLUMN must be set to eighty. If the eighty-column board can display lower-case 
letters, change FDISP from zero to one. If it requirestrue ASCII characters (high bit off) 
set EORCHR to $80. 
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FCONT “ Operating System Controller 

This routine should initialize the eighty-column board before the code at the label IN1 Is 
exectuted. The board should be re-initialized after each reset, i. e., at the label RESET. 

SGTXY - Go To X-Y 

The cursor must be positioned to the vertical position specified by CV (0-23) and the 
horizontal position specified by CH (0-79). 

SHOME Clear Screen and Home Cursor 

The screen is cleared from line WNDT to WNDB, and the cursor Is placed in column one 
of line WNDT. This will not always be the full screen, so hardware clears cannot be used. 

SPRHV - Print on CH and CV 

The character in the accumulator must be placed on the screen at CV, CH. The cursor 
must remain unchanged. 

Clock Calendar Card 

Adding a clock calendar card can do more than automatically set the date at 
initialization time. The operating system is set up to output the amount of time required 
for assemblies, or the amount of time spent in the monitor. The monitor can also print 
the current time if a clock is available. 

If theCaliforniaComputerSystemsClock/CalendarCard Is Installed, it can be activated 
by reassembling the operating system. For any other card, inspect the following 
subroutines and the CLOCK macro for possible changes. The CLOCK macro is 
contained in OPSYS.MACROS. 

SCLOK - Read Clock Card 

On input, the A register contains a code (set by tby the CLOCK macro, which calls this 
subroutine) Indicating the part of the time needed. On output, the A register contains 
the seconds, minutes, hours, date or year, as per the Input code. 

SDATE - Set Date 

Sets DATE and DATE+ 1 to the compressed date format mentioned above. 

STIME - Get Current Time 

The current time is stored in M1L, M1H and M2L.The bytes arethe current hour, minute 
and second, respectively. The time is also stored in TSTR as a string. 
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STIMI - Time Initialization 

Sets the common area variables HOUR, MINUTE and SECOND to the current time. 
STIMP - Print Elapsed Time 

The amount of time that has elapsed since HOUR, MINUTE and SECOND were set is 
printed on the screen. 

STSTR - Time String 

Converts the time in M1L, M1H and M2L into an Apple II screen character string and 
stores the string in the common area variable TSTR. 


General Comments 


During any change of the operating system, the order of the table of addresses and 
variables (through LNAMES) which appear at thebeginning of themain routine must be 
unchanged. The monitor, assembler, and link editor use these routines and variables, 
accessing the subroutines by indirect JMP instructions directed at the table of 
addresses. Note that this does not prevent the subroutines themselves from being 
changed, provided the input and output conventions remain the same. 

Any change to the operjating system must leave the operating system small enough to fit 
between $B000 and $BFFF. If the operating system gets too long, a Backwards Ref by 
ORG error results. This Is caused by the ORG statement at the beginning of the RWTS 
subroutine. 

If the RWTS subroutine is altered, check for time-critical code. Specifically, page 
boundaries must remain as they are, or disk writes will not work. 

Although some of the disk routines are included in the operating system, thereare quite 
a few that are in the monitor or assembler. Thus It is not possible to interface the 
assembler to a radically different disk system. So long as the disk system has thirty-five 
(or forty) tracks and sixteen sectors of 256 bytes, replacing RWTS should work. 

For double sided disks, or disk RAM cards, consider implementing them as alternate 
slot, drive numbers. Page two of the 4K block of memory at $D000 on a 16K RAM card 
may be used for custom disk drivers. 
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MCS6500 Microcomputer Family Programming Manual, MOS Technology, Inc., 1976. 


The definitive guide on what the 6502 does. Explanation of the instructions go so far 
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another book is being used to learn from; the texts do not always go into as much 
detail on an Instruction as one might like. 
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do interfacing with DOS from assembler language. 
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BY MIKE WESTERFIELD ♦ 4624 0063 96E1 STA FRl+5, 
COPYRIGHT (C) JANUARY 1983 * 4626 0066 94DC STY FR1,X 
BY HAYDEN BOOK COMPANY, INC. * 4626 0067 DBNE X,IN7 
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STRING,X 5841 0000 * BY HAYDEN BOOK COMPANY, INC. 

#>STRING SET ADDR OF 5842 0000 ♦ 

#<STRING STRING 5843 0000 ♦ INPUTS; 
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Absolute address 54,56 
Accumulator addressing mode 54 
Address field 56 
Address reference DC type 71 
Address DC type 71 
Addressing modes 55 
AGO directive 90 
AIF directive 90 
AINPT 6, 90 
AMID set symbol 89 
ANOP directive 92 
APEND command 43,44 
APPEND directive 16, 49, 64,67, 75, 
106, 167 

Arithmetic operations 55, 59,60 
ASCII characters 73 
ASCII files 20 
ASML command 14 
ASMLG command 14, 16 
ASRCH set symbol 89 
ASSEMBLE command 14,16 
Assembler directives 48, 51, 53, 54, 63, 
68, 151, 152 
Attributes 92 
Binary 

DC type 72 
file 95, 197 
numbers 59 
Boolean expression 88 
BRUN command 12, 16 
CATALOG command 16 
Character 

buffer 27, 36, 40 
constants 59 
DC type 72 


CHECK command 17 
Clock calendar card 23, 213 
CMPL command 14, 17 
CMPLG command 14, 17 
Code segment 5 
Comment 151 
field 61 
lines 51, 52, 
continuation line 52 
COMPILE command 14, 17 
Compilers 203 

COMPRESS command 12, 17 
Concatenation of symbolic paramters 
87 

Conditional assembly 102 
branches 159 
directives 63, 79, 86 
branches 52 
Constants 66 
Continuation line 52, 61 
Copy buffer 27, 31, 36, 39 
COPY 

command 18, 43, 44 
directive 49, 76, 167 
Count attribute 92 
Cursor movement 32, 37 
Data areas 170 
Data segement 65, 66, 69 
DATA directive 64, 65 
Date 11, 197, 212, 213 
DC directive 64, 70, 153, 160 
DELETE command 12, 18, 39 
DOS 14, 18 
Double precision 
DC type 73 
subroutines 106 
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Drive parameter 15, 45 
DS directive 64. 66. 70, 153 
Duplicate labels 160 
EDIT command 14, 18 
Eighty-column boards 212 
EJECT directive 74 
End of line marker 23, 26, 28 
END directive 45, 63, 64, 163, 167 
ENTRY directive 64, 65, 69 
EQU directive 56, 64, 75, 161 
Error messages 47, 159 
ERROR directive 49, 77 
Escape mode 37, 38 
EXPND directive 19. 49. 77 
External labels 45 
FERR 107 
Floating point 106 
DC type 73 
macros 108 
numbers 163 
subroutines 106 
Four byte Integer 
DC type 71 
subroutines 106 
FPLEN directive 49, 75 
FREE command 19, 106 
GEN directive 49, 77, 155 
GEQU directive 49, 56, 64, 66. 75, 157, 
161, 165 

GLBA definition statement 87 
GLBB definition statement 87 
GLBC definition statement 87 
Global label 5, 64, 65, 66, 96. 160, 161, 
164, 168, 169 

Global symbolic parameters 87 
Hexadecimal 
DC type 72 
number 58 
HIMEM 98 
Insert and delete 33 
Insert commands 39 
Instruction 51, 53, 54, 151 
Integer 

numbers 57 
DC type 70 
subroutines 106 


KEEP 

directive 49, 64, 67, 68, 76, 62 
parameter 48, 49, 96, 98 
Keyword parameters 104, 108, 160 
Label 53, 55, 56, 151, 161 
Language commands 24 
Language number 24 
LCLA definition statement 87 
LCLB definition statement 87 
LCLC definition statement 87 
Length attribute 93 
Library files 99 
Link editor 14, 19, 157 

command parameters 97 

LIST 

directive 49, 77 
parameter 48, 98 
LOAD command 13, 19 
Local label 45, 64, 65, 66, 69, 160 
Local symbolic parameters 87 
Location counter 53, 160 
LOCK command 12, 19 
Logical expressions 59, 60 
LOMEM 98 

Lower case adapter 30 
Macro 54, 151, 152, 155 

call 51, 79, 82. 84. 85, 102, 160 

definition 43, 79, 81. 85, 106, 108, 

162, 165 

file 43, 76, 79 

language 81 

libraries 76, 77, 105, 106, 155, 156, 
165 

operands 103 
statement 165 
directive 80, 106 
MARGIN command 19 
Maximum error level 75 
MCOPY directive 49, 64, 68. 74, 76. 79. 

80, 105, 106 
MEND directive 80, 106 
MERR directive 49, 74 
MERR directive 74 
MEXIT directive 80 
MLOAD directive 77, 79, 156 
MNOTE directive 80 
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Model statements 82 
Monitor commands 14 
Monitor 11 

MSB directive 49, 73, 78 
Multiple operand 103 
Names parameter 48, 96 
Naming conventions 106 
NEW command 14, 19 
NOEXPAND command 20 
Non-keyboard characters 34 
Null string 86 

Object code 14, 45, 46, 47, 95, 157, 198 
Octal numbers 58 
One byte Integer DC type 71 
Operand 151, 162 
field 53, 54,152 
syntax 163 

Operating system 6, 211 
Operation code 53, 54, 151, 161, 165 
ORG directive 56, 64, 68, 74, 49, 98, 
161, 167, 168, 

PAGE directive 56, 74, 161, 168 
Partial assemblies 157 
Pass one 

assembler 45 
linker 96, 99 
Pass two 

assembler 45 
linker 96, 99 
PEEK command 20 
Positional paramters 83, 84, 85, 104, 
160 
PRINT 

command 21 
parameter 49, 98 
subroutine 106 
printer 21, 22, 47 
drivers 211 

PRNT directive 47, 49, 64, 68, 78, 162 

PROFF command 21 

Program counter 57 

Program segment 45, 64, 68, 160 

PRON command 22 

QUIT command 22 

Recoverable errors 167 

Relative 


addressing 163 
branch 5 

Relocation dictionary 199 
RENAME command 12, 22 
Repeat 

count 70 
feature 32, 38, 39 
Replacement string 27, 35, 40 
Reserve memory 168 
RESET command 22 
RESTORE command 22 
ROOT file 96, 170, 205 
RUN command 14, 22 
RWTS 166, 167, 213 
SAVE command 13, 22 
Scrolling 33 

Search and replace 29, 30, 40 

Search string 27, 35, 40 

Sequence symbol 90, 164 

Set symbol 88, 164 

SETA 88 

SETB 88 

SETC 88 

Severity codes 157 
Slot parameter 15, 45 
Soft reference DC type 71 
Source 

file 13, 43, 44, 95, 197, 205 
lines 51, 151 
Stack 162 

START directive 63, 64, 68, 167 
String buffer 27, 29 
SUBLIB SOURCE 9, 101 
Subroutine library 51, 106, 168, 169 
Subroutine 5 

Subscripting parameters 85, 86, 164 
SWITCH command 23 
SYMBL directive 49, 77 
Symbol table 45, 96, 99, 170 
SYMBOL parameter 98, 99 
Symbolic parameter 83 86, 108,161, 
164 

concatenation 87 
SYSFERR 107 
SYS FIRST 44 
SYSRITE 106 





364 


ORCA/M 


System configuration 6 
SYSTEM DISK 7, 8, 45 
System source disk 6, 7, 9, 37, 101 
TAB 23 

cursor movement 28, 38 
skip 23 
stop 23, 53 

Terminal error 45, 46, 166, 169 
Text edit buffer 25, 43, 

Text edit window 25 
Text files 205 
Text window control 33 
Time 213 

command 23 
TITLE directive 74 
Type attribute 93 


UNLOCK 12, 23 
Unresolved label 56 
Update number 22 
USER 6, 24 

USING directive 64, 66, 69 
Volume 

command 15, 24 
number 15, 24, 45 
parameter 15, 49, 98, 166 
VTOC 5, 24, 166 
Wildcard character 13, 15 
WRITE subroutine 106 
Zero page 55, 56, 75, 153, 160, 16 

&SCNT 88 










